Operator guide to required environment variables, multi-worker settings, external dependencies, and monitoring endpoints when deploying to production.
This page is a checklist of the settings an operator must verify when deploying Cloosphere to production.
Expand each item to see the exact values and cautions.
Admin panel settings (GUI) are stored in the DB as PersistentConfig and applied automatically. This page covers the items you cannot change through the GUI — environment variables and external dependencies.
Point CLOOSPHERE_PUBLIC_URL at an external HTTPS FQDN
Variable
Use
Example
CLOOSPHERE_PUBLIC_URL
External access base URL. Used for embed widget callbacks, manifest validDomains auto-computation, and more
https://cloosphere.yourdomain.com
CLOOCUS_PUBLIC_URL
Public base URL for the SR (Service Request) feature. Set together with SR_KEY to enable SR
https://cloosphere.yourdomain.com
When CLOOSPHERE_PUBLIC_URL is unset:
Embed widget callback URLs are wrongly exposed as an internal IP/host
Teams bot manifest validDomains computation errors
(The SR feature is controlled separately by CLOOCUS_PUBLIC_URL + SR_KEY.)Always specify an HTTPS public FQDN. Behind a proxy (Nginx/Cloudflare), enter the externally visible URL.
Verify the PostgreSQL connection through DATABASE_URL
Variable
Tier
Use
DATABASE_URL
Required
PostgreSQL connection string
DATABASE_SCHEMA
Recommended
Schema separation for multi-tenant deployments (default public)
If the connection drops, /health/db returns 503 plus an error detail. Check this endpoint right after deploying.
Apply Alembic migrations to the correct schema at the latest revision
The deployed code version and the DB schema version must match. A missing migration surfaces at runtime as a missing column or table error.
In a multi-worker environment migrations must run exactly once. Concurrent workers attempting migration collide (fixed by an automatic lock in recent versions). See the “Serialize container startup” item in the multi-worker group for how to serialize.
Set backup cadence for PostgreSQL, file storage, and the AGE graph
PostgreSQL — PersistentConfig, users, audit logs, and other core data
File storage — uploaded documents and images
AGE graph — the Knowledge Graph lives inside PostgreSQL, but large graphs are safer with their own backup cadence.
Establish a regular backup policy that covers all three.
Set REDIS_URL (PersistentConfig sync · session sharing)
Variable
Tier
Use
REDIS_URL
Multi-worker
Required for multi-worker, optional for a single worker
REDIS_SENTINEL_HOSTS
Optional
When using Redis Sentinel
REDIS_SENTINEL_PORT
Optional
(default 26379)
REDIS_URL is required in multi-worker environments. Operating without Redis:
PersistentConfig is held only in per-worker memory → settings drift between workers
Session data such as per-user agent selection is lost
Teams bot / embed widget user context is lost
When the Redis connection fails, Cloosphere fast-fails on a 5-second timeout and switches to an in-memory fallback (single-worker mode). In multi-worker deployments, monitor Redis availability through the health endpoints.
Mount the same file storage volume on every worker
If workers reach different local files, a file uploaded to one worker does not exist on another. Mount the same shared volume (NFS, object storage, etc.) identically on every worker.
Keep environment variables and the timezone (TZ) identical across workers
Mismatched environment variables → behavior differs depending on which worker a user lands on
Mismatched timezone (TZ) → schedule and audit log timestamps disagree between workers
Verify every worker boots with the same environment variable set and the same TZ.
Serialize container startup to avoid migration conflicts
Item
Impact when missed
Alembic migrations run exactly once
Concurrent workers collide (fixed by a lock in recent versions)
Alembic migration conflicts are resolved by an automatic lock in recent versions, but serializing container start order — for example, waiting for the first worker’s healthcheck to pass before starting the rest — is safer.
Remove the single point of failure with Redis Sentinel or Cluster (recommended)
Recommended A single Redis instance takes the whole service down when it fails. Use Sentinel or Cluster for high availability. Configure it through REDIS_SENTINEL_HOSTS / REDIS_SENTINEL_PORT.
Requested scopes (openid email profile is the default)
OAUTH_PROVIDER_NAME
Provider name shown on the sign-in screen
Keycloak organization sync runs on the client_credentials grant flow. Once all the variables above are set, the Keycloak sync option becomes available on the Organization Management screen.
See the Authentication items under General settings for more.
Teams bot registration · manifest upload
To operate a Microsoft Teams bot:
TEAMS_BOT_APP_ID=<Azure Bot Client ID>TEAMS_BOT_APP_PASSWORD=<Client Secret>TEAMS_BOT_TENANT_ID=common # or a single-tenant GUIDTEAMS_BOT_ENABLED=trueTEAMS_BOT_BACKEND_TIMEOUT=300TEAMS_BOT_DEFAULT_LOCALE=ko-KR
The Teams bot requires Redis in multi-worker environments. Per-user agent selection state has to be shared across workers.
Size the AGE pool to your KG data volume (recommended)
Recommended If you use the Knowledge Graph, size the connection pool to your data volume.KG fan-out extraction uses many concurrent connections, so at larger volumes pool exhaustion can fail a sync. Adjust the pool size to match.
Variable
Default
< 10M nodes
10M–100M nodes
> 100M nodes
AGE_POOL_MIN
2
2
4
8
AGE_POOL_MAX
32
16
32 (default)
64+
On pool exhaustion Cloosphere automatically performs 5 retries with exponential backoff (0.1s × 2^attempt). Seeing [age_service] pool initialized in the logs means initialization succeeded. Repeated PoolError or connection pool exhausted means it is time to raise the pool size one tier.
Recommend /health/db for the CI/CD readiness probe and /health for the liveness probe.
The System Diagnostics panel is not an always-on screen inside the admin panel. It appears only inside the “Service Connection Error” screen — shown when the app fails to start — and only for users signed in as an admin. It lists each component as OK / ERROR with the error message, so during an outage you can tell immediately whether the DB, Redis, or the task queue is down. For routine status checks, call the endpoints above directly.
Verify the audit log license feature
The license must include the audit log (audit_log) feature for operational activity to be recorded. See Audit Logs for how to check and use it.
