observal server

July 6, 2026 · View on GitHub

Manage the embedded Observal server stack (PostgreSQL, ClickHouse, Redis, API, web UI).

All commands operate on the local Docker Compose stack. The upgrade, rollback, and versions commands require super_admin role.

Subcommands

Command	Description
`server start`	Start all services
`server stop`	Stop all services
`server restart`	Restart all services
`server status`	Show service status
`server logs`	View service logs
`server install`	Download dependency binaries
`server config`	Show current configuration
`server reset`	Wipe all data
`server upgrade`	Upgrade to a new version
`server rollback`	Roll back to previous version
`server versions`	List available versions

`observal server start`

Start all services and the Observal API server. On first run, downloads database binaries and initializes data directories.

observal server start
observal server start --port 9000
observal server start --background

Option	Short	Default	Description
`--port`	`-p`	8000	API port
`--host`		0.0.0.0	Bind address
`--background`	`-d`	false	Run in background (daemonize)

If the default port is in use, the server automatically tries fallback ports (8001, 8002, 8010, 8100).

`observal server stop`

Gracefully shut down all services in reverse order: API, Redis, ClickHouse, PostgreSQL.

observal server stop

`observal server restart`

Stop and restart all services.

observal server restart
observal server restart --port 9000

Option	Short	Default	Description
`--port`	`-p`	8000	API port
`--host`		0.0.0.0	Bind address

`observal server status`

Show a table of all service statuses (running, stopped, not initialized) with their ports.

observal server status

Output:

        Observal Service Status
┌────────────┬─────────┬──────┐
│ Service    │ Status  │ Port │
├────────────┼─────────┼──────┤
│ Postgres   │ running │ 5480 │
│ Clickhouse │ running │ 8124 │
│ Redis      │ running │ 6380 │
│ Api        │ running │ 8000 │
└────────────┴─────────┴──────┘

`observal server logs`

Show or follow service logs.

observal server logs
observal server logs postgres
observal server logs api --follow
observal server logs redis --lines 200

Argument	Description
`[SERVICE]`	Service name: `postgres`, `clickhouse`, `redis`, `api`. Omit for all.

Option	Short	Default	Description
`--follow`	`-f`	false	Follow log output (like `tail -f`)
`--lines`	`-n`	50	Number of lines to show

`observal server install`

Download database dependency binaries (PostgreSQL, ClickHouse, Redis). Runs automatically on first server start, but can be invoked manually to pre-download.

observal server install
observal server install --upgrade

Option	Description
`--upgrade`	Re-download even if already installed

`observal server config`

Show current server configuration (ports, data directories, API URL).

observal server config

`observal server reset`

Stop all services and wipe all data (databases, config, keys). Requires re-initialization on next start.

observal server reset
observal server reset --force

Option	Short	Description
`--force`	`-f`	Skip confirmation prompt

Warning: This is destructive. All traces, users, agents, and configuration will be permanently deleted.

`observal server upgrade`

Upgrade the server to the latest or a specified version. Pulls new Docker images from GHCR, creates a database backup, and recreates containers with a health check.

Requires super_admin role.

observal server upgrade
observal server upgrade --version 0.9.0
observal server upgrade --dry-run
observal server upgrade --skip-backup --force

Option	Short	Default	Description
`--version`	`-v`	latest	Target version (e.g. 0.9.0)
`--skip-backup`		false	Skip pre-upgrade database backup
`--dry-run`		false	Show upgrade plan without applying changes
`--force`	`-f`	false	Skip interactive confirmation

What happens during an upgrade:

Resolves target version (latest from GitHub if not specified)
Verifies the Docker image exists on GHCR
Acquires an upgrade lock (prevents concurrent upgrades)
Creates a database backup (unless --skip-backup)
Pulls new images: ghcr.io/observal/observal-{api,web}:<version>
Updates .env with the new version
Recreates containers via docker compose up -d
Runs health checks for up to 120 seconds
If health check fails, automatically rolls back

After a successful upgrade:

✓ Upgraded to v0.9.0
  Backup: ~/.observal/backups/v0.8.0-20260523T100000
  Rollback: observal server rollback

`observal server rollback`

Rollback the server to a previous version from backup. Restores the database, reverts Docker images, and recreates containers.

Requires super_admin role.

observal server rollback
observal server rollback --from-backup ~/.observal/backups/v0.7.0-20260521T120000
observal server rollback --force

Option	Short	Description
`--from-backup`		Path to a specific backup directory (default: most recent)
`--force`	`-f`	Skip interactive confirmation

If no backup path is specified, the most recent backup is used.

`observal server versions`

List available server versions from GHCR alongside local backup status. Shows which versions have images available and which have local database backups.

Requires super_admin role.

observal server versions

Output:

         Server Versions
┌─────────┬────────────┬──────┬─────────┐
│ Version │ Status     │ GHCR │ Backup  │
├─────────┼────────────┼──────┼─────────┤
│ 0.9.0   │ ← current │ ✓    │ -       │
│ 0.8.0   │            │ ✓    │ 42 MB   │
│ 0.7.0   │            │ ✓    │ 38 MB   │
└─────────┴────────────┴──────┴─────────┘

Permissions

Command	Role required
`start`, `stop`, `restart`, `status`, `logs`, `install`, `config`, `reset`	None (local shell access)
`upgrade`, `rollback`, `versions`	super_admin

The super_admin check calls /api/v1/auth/whoami and verifies the authenticated user's role. If you're not logged in or lack the role, the command exits with a permission error.

Upgrades guide for manual and zero-downtime upgrade strategies
Backup and restore for database backup details
observal self for CLI version management (separate from server)