Docker Deployment

ZPan ships as a single Docker image. By default it uses an embedded SQLite database (better-sqlite3). For production multi-replica deployments you can opt into Turso (libSQL) as a shared remote database.

Default: local SQLite

No extra configuration needed. Mount a volume so the database survives container restarts:

services:
  zpan:
    image: ghcr.io/saltbo/zpan:latest
    ports:
      - "8222:8222"
    environment:
      PORT: 8222
      BETTER_AUTH_SECRET: <generate with: openssl rand -base64 32>
      BETTER_AUTH_URL: https://your-domain.example
      DATABASE_URL: /data/zpan.db
    volumes:
      - zpan-data:/data
    restart: unless-stopped

volumes:
  zpan-data:

Migrations run automatically at startup. The compose files in this repository also include an optional downloader service using the CLI-only tag (ghcr.io/saltbo/zpan:latest-cli). On first start, zpan downloader up prints a device authorization URL in the container logs and waits. Open that URL as an admin user; after approval the downloader registers itself, saves its token under /home/zpan/.config/zpan/config.yaml, and continues running.

Turso (libSQL) opt-in

Set TURSO_DATABASE_URL to switch from local SQLite to a Turso (or self-hosted libSQL) database. TURSO_AUTH_TOKEN is required for remote URLs; it can be omitted for local file:// URLs.

services:
  zpan:
    image: ghcr.io/saltbo/zpan:latest
    ports:
      - "8222:8222"
    environment:
      PORT: 8222
      BETTER_AUTH_SECRET: <generate with: openssl rand -base64 32>
      BETTER_AUTH_URL: https://your-domain.example
      TURSO_DATABASE_URL: libsql://your-db-name-orgname.turso.io
      TURSO_AUTH_TOKEN: <your-turso-auth-token>
    restart: unless-stopped

When TURSO_DATABASE_URL is present:

DATABASE_URL is ignored.
Migrations are applied automatically at startup via drizzle-orm/libsql/migrator.
TURSO_AUTH_TOKEN may be omitted only for file:// URLs (local libSQL files).

Running migrations manually against Turso

TURSO_DATABASE_URL=libsql://your-db.turso.io \
TURSO_AUTH_TOKEN=your-token \
pnpm db:migrate

drizzle.config.ts automatically switches to the turso dialect when TURSO_DATABASE_URL is set, so pnpm db:generate and pnpm db:migrate work against Turso without any extra flags.

Obtaining a Turso auth token

turso db tokens create your-db-name

Or create one in the Turso dashboard.

Pro licensing and traffic sync

ZPan refreshes its entitlement certificate every 6 hours and syncs metered traffic every 10 minutes via built-in background timers. The Docker container runs a persistent Node.js process, so these timers fire automatically — no external cron is required.

If you prefer an explicit external trigger (e.g. to integrate with your monitoring or to refresh immediately after a plan change), you can call the refresh endpoint manually:

Setup

Generate a secret:
```
openssl rand -hex 32
```

Add the env var to your container environment:

environment:
  REFRESH_CRON_SECRET: <the-secret-from-step-1>

Trigger a refresh or traffic sync with HTTP POST:

POST https://your-domain.example/api/licensing/refresh-cron?secret=<REFRESH_CRON_SECRET>

POST https://your-domain.example/api/licensing/traffic-sync-runs?secret=<REFRESH_CRON_SECRET>

To run on a schedule via host cron, add to your crontab:

0 */6 * * * curl -s -X POST "https://your-domain.example/api/licensing/refresh-cron?secret=<REFRESH_CRON_SECRET>"
*/10 * * * * curl -s -X POST "https://your-domain.example/api/licensing/traffic-sync-runs?secret=<REFRESH_CRON_SECRET>"

If REFRESH_CRON_SECRET is not set, the endpoint returns 401 for all requests.

3.8 KiB Raw Blame History