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 | gcs. |
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).
Vector store and embeddings
Search in UIGraph understands meaning, not just keywords, which is what these settings power. The bundled deploy runs everything it needs, so a standard install sets none of them. Change them to use a managed vector store or a hosted embedding provider instead.
| Variable | Required | Default | Description |
|---|---|---|---|
VECTOR_BACKEND | No | qdrant | qdrant | s3vectors. |
QDRANT_URL | No | http://qdrant:6333 | Where to reach Qdrant, when VECTOR_BACKEND is qdrant. |
EMBEDDING_BACKEND | No | ollama | ollama | bedrock | openai. |
EMBEDDING_MODEL | No | nomic-embed-text | Which embedding model to use, named as your chosen backend names it. |
EMBEDDING_URL | No | http://ollama:11434 | Where to reach the embedding service. |
Search results from one model cannot be compared with results from another. If you change EMBEDDING_MODEL or EMBEDDING_BACKEND once you already have data, everything indexed before the change has to be re-indexed before search works properly again.
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).