Quickstart

​

Before you start

​

What each service is

​

Configure the installation

cp .env.example .env

openssl rand -base64 32   # APP_DATA_ENCRYPTION_KEY
openssl rand -hex 32      # APP_OPERATOR_TOKEN

APP_DATABASE_URL=postgres://omniflow:omniflow@postgres:5432/omniflow?sslmode=disable
APP_VALKEY_URL=redis://valkey:6379/0
APP_REMNAWAVE_URL=https://panel.example.com
APP_REMNAWAVE_TOKEN=<your Remnawave API token>
APP_OPERATOR_TOKEN=<generated above>
APP_DATA_ENCRYPTION_KEY=<generated above>
APP_DEFAULT_CURRENCY=RUB
APP_TELEGRAM_TOKEN=<from BotFather, or leave empty>

APP_ADMIN_COOKIE_SECURE=false
APP_CUSTOMER_COOKIE_SECURE=false

​

Bring the stack up

docker compose up --build postgres valkey migrate api bot worker

docker compose --profile web up --build

• API — http://localhost:8080
• Customer account — http://localhost:3000
• Operator workspace — http://localhost:3000/admin

​

Create the first owner

docker compose logs api | grep setup

level=WARN msg="no administrator exists yet; redeem this one-time setup token at /admin/setup" token=… expires_in=30m0s

​

Enable two-factor authentication

​

Prove that it works

curl -s http://localhost:8080/livez
# {"status":"ok","version":"dev"}

curl -s http://localhost:8080/readyz

{
  "status": "ready",
  "checks": [
    {"name": "postgres", "healthy": true, "checkedAt": "2026-08-13T09:12:04Z", "latencyMs": 2},
    {"name": "valkey", "healthy": true, "checkedAt": "2026-08-13T09:12:04Z", "latencyMs": 1},
    {"name": "remnawave", "healthy": true, "checkedAt": "2026-08-13T09:12:04Z", "latencyMs": 84}
  ]
}

​

What does not work on a fresh clone

• The durable job queue has no schema. Omniflow enqueues background work with River, but no committed migration creates River’s own tables and nothing in the stack runs River’s migrator. On a database migrated only by docker compose up migrate, worker therefore exits at startup logging start River, and any settlement — which inserts a fulfillment job in the same transaction as the money — rolls back. A purchase cannot complete until that migration exists. See Your first sale for exactly where a test purchase stops, and Jobs and queues for what the queue is meant to do.
• The transactional outbox is written and never published. Three topics are inserted, nothing ever sets published_at, and no dispatcher exists. The outbox counters on the dashboard and at GET /v1/admin/outbox therefore grow permanently, APP_RETENTION_OUTBOX_DAYS deletes nothing, and the “outbox lag” attention item on /admin is expected rather than diagnostic.
• There is no tracer provider. The code opens spans across HTTP, Telegram updates, jobs, and SQL, but no exporter is installed and no OTEL_* variable is read anywhere in the repository. Setting the standard OpenTelemetry variables changes nothing; the global provider stays a no-op. Metrics and logs are what an installation actually emits — see Observability.
• Every binary reports "version":"dev". Nothing stamps a version at build time, including the released images, so /livez, the diagnostics bundle, and the telemetry heartbeat all say dev.
• The panel’s settings sections do not configure the runtime. Saving a section stores a document; the Remnawave connection, the bot, the operator group, maintenance policy, telemetry, backups, and the payment adapters all come from environment variables read at startup. See Installation settings.
• Nothing restarts a crashed process. No core Compose service declares a restart: policy, so a process that exits stays down until somebody notices. Add one for anything long-lived.
• A browser-uploaded support attachment has no volume. APP_SUPPORT_ATTACHMENT_DIR defaults to /var/lib/omniflow/support-attachments and is read by both api and worker, but compose.yaml mounts a volume there for neither. Files live in the container’s writable layer until it is rebuilt, and the worker cannot reclaim files it cannot see.

​

Next steps