UIGraph API (uigraph-api)
uigraph-api is the core backend. It owns the database, authentication, asset storage, the screenshot worker, and every REST endpoint the UI and MCP server call. It is the first service to start, and everything else depends on it.
Core
The essentials: where the API listens, and how it reaches its database, cache, and the domain it is served on.
| Variable | Required | Default | Description |
|---|---|---|---|
POSTGRES_URL | Yes | — | Database DSN. Points at the bundled Postgres; repoint at a managed database to use your own. |
UIGRAPH_SECRET_KEY | Yes | — | AES-256-GCM master key (32 bytes) used to encrypt sensitive database values, including OIDC client secrets and SAML SP private keys. Generate with openssl rand -hex 32. Existing encrypted values cannot be read after changing or losing it. |
HOST | No | — | Which network interface to listen on. Leave empty to accept connections on all of them. |
PORT | No | 8080 | Port the API listens on. |
REDIS_URL | No | redis://redis:6379 | Redis URL. Points at the bundled Redis. |
UIGRAPH_DOMAIN | No | localhost | Public domain UIGraph is served on. |
UIGRAPH_COOKIE_DOMAIN | No | — | Set this to .example.com if you want one sign-in to work across subdomains. Leave it empty and a session is only valid on the exact host it was issued from, which is what you want when UIGraph is served from a single URL. See SSO Security & Operations. |
UIGRAPH_LICENSE_KEY | No | — | License key. Not required for self-hosted use. |
URLs
| Variable | Required | Default | Description |
|---|---|---|---|
UIGRAPH_PUBLIC_URL | No | http://localhost:3000 | Externally reachable base URL. UIGraph derives OIDC callbacks, SAML ACS/entity ID/metadata URLs, and secure-cookie behavior from it. |
UIGRAPH_FRONTEND_URL | No | http://localhost:3000 | Where the backend redirects the browser after OIDC or SAML login, and where the screenshot worker navigates to capture frames. |
UIGRAPH_INTERNAL_FRONTEND_URL | No | http://uigraph-ui | In-network address of the UI container, used for server-to-UI requests inside the Docker network. |
Bootstrap admin
| Variable | Required | Default | Description |
|---|---|---|---|
UIGRAPH_ADMIN_EMAIL | No | admin@uigraph.app | Email of the admin user seeded on first boot (empty database). |
UIGRAPH_ADMIN_PASSWORD | No | admin | Initial admin password. Leaving it as admin forces a password change at first login. |
Object storage
The API signs and stores assets here. The same STORAGE_* values must be set on UIGraph Gateway; they must agree. The bundled deploy uses MinIO; the s3 backend is S3-compatible, so the same keys point UIGraph at AWS S3, Cloudflare R2, or any S3-compatible provider.
| Variable | Required | Default | Description |
|---|---|---|---|
STORAGE_BACKEND | No | minio | minio (bundled) | s3. Google Cloud Storage is on the roadmap and not available yet. |
STORAGE_ENDPOINT | No | — | In-network storage endpoint the service signs against (e.g. http://minio:9000). |
STORAGE_PUBLIC_ENDPOINT | No | — | Browser-reachable storage host used for presigned asset URLs (e.g. http://localhost:9000). Must resolve from the user's browser. Falls back to STORAGE_ENDPOINT. |
STORAGE_BUCKET | No | uigraph | Bucket name. |
STORAGE_ACCESS_KEY | No | — | Access key. For bundled MinIO this is also the root user. |
STORAGE_SECRET_KEY | No | — | Secret key / MinIO root password. |
STORAGE_REGION | No | us-east-1 | Region for the s3 backend. Use auto for Cloudflare R2. |
STORAGE_FORCE_PATH_STYLE | No | true when STORAGE_ENDPOINT is set | Path-style addressing, required by MinIO and R2; set false for AWS S3. |
The bundled MinIO container's root credentials (MINIO_ROOT_USER / MINIO_ROOT_PASSWORD) must match STORAGE_ACCESS_KEY / STORAGE_SECRET_KEY; see Storage (MinIO).
Screenshots
UIGraph captures screenshots of your UI with a headless browser.
| Variable | Required | Default | Description |
|---|---|---|---|
UIGRAPH_CHROMIUM_PATH | No | /usr/bin/chromium in the official image | Where Chromium or Chrome is installed. Set this if you build your own image and screenshots stop working; leave it empty to let UIGraph find the browser itself. |
Figma integration
The Figma OAuth app powers importing designs directly from Figma. Leave blank to disable. Create the app at figma.com/developers.
| Variable | Required | Default | Description |
|---|---|---|---|
FIGMA_CLIENT_ID | No | — | OAuth client ID of your Figma app. |
FIGMA_CLIENT_SECRET | No | — | OAuth client secret of your Figma app. |
Register this redirect URL in your Figma app: UIGRAPH_PUBLIC_URL + /api/v1/figma/callback (for example http://localhost:3000/api/v1/figma/callback).
GitHub App
The GitHub App is what users install when they connect a repository and onboard it with GitHub Actions. Leave these blank to disable it. Every self-hosted installation needs its own app. See GitHub App for how to create one and where each value below comes from.
| Variable | Required | Default | Description |
|---|---|---|---|
GITHUB_APP_ID | No | — | App ID shown on the app's settings page after you create it. |
GITHUB_APP_SLUG | No | — | URL name of the app, the last part of its public page address. |
GITHUB_APP_CLIENT_ID | No | — | Client ID of the app. |
GITHUB_APP_CLIENT_SECRET | No | — | Client secret. Generate it on the app's settings page. |
GITHUB_APP_PRIVATE_KEY_BASE64 | No | — | Private key of the app, base64-encoded. Generate the key on the app's settings page and encode the downloaded .pem file. |
GITHUB_WEBHOOK_SECRET | No | — | The same secret you set in the app's Webhook section. Leave it empty and UIGraph does not accept webhooks at all, so onboarding runs are never followed. |
GITHUB_API_URL | No | https://api.github.com/ | GitHub API base URL. Change it for GitHub Enterprise Server. |
GITHUB_WEB_URL | No | https://github.com | GitHub website base URL. Change it for GitHub Enterprise Server. |
The first five variables go together. Set all of them or none of them, otherwise the API refuses to start. Setting GITHUB_WEBHOOK_SECRET on its own counts as a partial setup and fails the same way.