Skip to main content

Operations

Day-2 concerns for a self-hosted UIGraph instance. All commands run from the uigraph-deploy/ directory.

Boot sequence​

On startup uigraph-api performs, in order:

  1. Connect to Postgres.
  2. Apply pending SQL migrations (embedded in the image, tracked in a schema_migrations table).
  3. Bootstrap the default org + admin user, idempotent, skipped if any org already exists.
  4. Start the HTTP server and report healthy on /healthz.

The uigraph-graphql, uigraph-gateway, and uigraph-ui services declare depends_on the API's health check, so they start only once the API reports healthy (after migrations + bootstrap).

Common tasks​

make docker-ps                          # service status
docker compose logs -f uigraph-api      # follow API logs
make docker-down                        # stop the stack (volumes preserved)
make docker-reset                       # wipe volumes and start fresh (re-runs migrations)

Upgrades​

The images are pinned to the latest tag. Pull the new images and recreate the containers; migrations run automatically on the next API boot.

docker compose pull
make docker-up

Backups​

Durable state lives in the three Docker volumes declared in docker-compose.yml:

  • postgres-data: the database (all application data).
  • minio-data: object storage (screenshots, diagram images, uploads).
  • redis-data: cache + queue (regenerable, but backing it up avoids a cold cache on restore).

Back these volumes up on your normal schedule. The application containers hold no state and can be recreated freely. If you repoint POSTGRES_URL or the STORAGE_* variables at managed services, rely on their backup tooling instead.

Going to production​

The bundled docker-compose.yml is tuned for local evaluation: it serves plain HTTP, publishes every service port to the host, and ships placeholder secrets. Before running it anywhere shared:

  • Replace every secret: UIGRAPH_SECRET_KEY and STORAGE_SECRET_KEY with openssl rand -hex 32, and the devpassword Postgres/MinIO passwords. Update the matching references in POSTGRES_URL and the STORAGE_* blocks.
  • Terminate TLS: put the stack behind your own reverse proxy or load balancer (nginx, Caddy, a cloud LB) that terminates HTTPS and forwards to uigraph-ui on port 3000. Set UIGRAPH_DOMAIN, UIGRAPH_PUBLIC_URL, and UIGRAPH_FRONTEND_URL to the public https:// URL. Serving over HTTPS is required for the session cookie's Secure flag and for SSO, see Authentication & SSO.
  • Close unneeded ports: only the UI (and MinIO's public endpoint, so browsers can fetch asset URLs) needs to be reachable. Remove the ports: entries for Postgres, the API, GraphQL, and the gateway, or bind them to 127.0.0.1.