Deployment Checklist - Cloosphere Guide

This page is a checklist of essential settings to verify when deploying Cloosphere to production.

Admin panel settings (GUI) are saved as PersistentConfig in DB and auto-applied. This page covers items that can’t be changed via GUI — environment variables and external dependencies.

Required Environment Variables

In production, missing these disables some features or causes abnormal behavior.

Public URL

Variable	Required	Use	Example
`CLOOSPHERE_PUBLIC_URL`	✅	External access base URL. Used for SR (Service Request), embed widget callbacks, manifest validDomains auto-computation, etc.	`https://cloosphere.yourdomain.com`

When CLOOSPHERE_PUBLIC_URL is unset:

SR (Service Request) feature is disabled — users can’t report issues
Embed widget callback URLs are wrongly exposed as internal IP/host
Teams bot manifest validDomains computation errors

Always specify as HTTPS public FQDN. Behind a proxy (Nginx/Cloudflare), enter the externally visible URL.

Database / Redis

Variable	Required	Use
`DATABASE_URL`	✅	PostgreSQL connection string
`DATABASE_SCHEMA`	⚠️	Schema separation in multi-tenant (default `public`)
`REDIS_URL`	⚠️	Required for multi-worker, optional for single worker
`REDIS_SENTINEL_HOSTS`	—	When using Redis Sentinel
`REDIS_SENTINEL_PORT`	—	(default 26379)

REDIS_URL is required in multi-worker environments. Operating without Redis:

PersistentConfig stored only in per-worker memory → inter-worker setting inconsistency
Per-user agent selection state and other session data lost
Teams bot / embed widget user context lost

When Redis connection fails, Cloosphere fast-fails with 5-second timeout and auto-switches to in-memory fallback (single-worker mode). In multi-worker, monitor Redis availability via health endpoints.

Knowledge Graph (AGE)

Variable	Default	Recommended
`AGE_POOL_MIN`	2	Small 2 / Medium 4 / Large 8
`AGE_POOL_MAX`	32	Small 16 / Medium 32 / Large 64+

KG fan-out extraction uses many concurrent connections, so pool exhaustion can fail sync.

Scale	Recommended
< 10M nodes	`AGE_POOL_MIN=2 AGE_POOL_MAX=16`
10M ~ 100M nodes	`AGE_POOL_MIN=4 AGE_POOL_MAX=32` (default)
> 100M nodes	`AGE_POOL_MIN=8 AGE_POOL_MAX=64`

On pool exhaustion, Cloosphere auto-performs 5 retries with exponential backoff (0.1s × 2^attempt). Seeing [age_service] pool initialized in logs indicates normal initialization. Repeated PoolError or connection pool exhausted means raise the pool size one tier.

SSO / OIDC Integration (optional)

To activate OAuth/OIDC SSO, set the following environment variables (Keycloak, Entra ID, Google all use the same interface).

OPENID_PROVIDER_URL=https://auth.example.com/realms/cloosphere/.well-known/openid-configuration
OAUTH_CLIENT_ID=cloosphere-app
OAUTH_CLIENT_SECRET=<strong-secret>
OAUTH_SCOPES="openid email profile"
OAUTH_PROVIDER_NAME=Keycloak

Variable	Use
`OPENID_PROVIDER_URL`	OIDC Discovery URL (`.well-known/openid-configuration`)
`OAUTH_CLIENT_ID`	Client ID registered with the IdP
`OAUTH_CLIENT_SECRET`	Client secret
`OAUTH_SCOPES`	Requested scopes (`openid email profile` is default)
`OAUTH_PROVIDER_NAME`	Provider name shown on the UI sign-in screen

Keycloak organization sync (since add35ab42): operates via client_credentials grant flow. When the above env vars are all set, the Keycloak sync option activates in Organization Management.

See General Settings — Authentication for details.

Teams Bot (optional)

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 single-tenant GUID
TEAMS_BOT_ENABLED=true
TEAMS_BOT_BACKEND_TIMEOUT=300
TEAMS_BOT_DEFAULT_LOCALE=ko-KR

Teams bot requires Redis in multi-worker environments. Per-user agent selection state must be shared across workers.

See the Teams Bot Guide for detailed setup.

Multi-Worker Operations Checklist

Item	Recommendation	Impact When Missed
`REDIS_URL` set	Required	PersistentConfig sync failure, session loss
Identical env vars across workers	Required	Inconsistent settings → different behavior per user
Alembic migrations	Run once only	Concurrent multi-worker conflicts (lock-fixed in latest version)
Shared file storage	Required	Workers access different local files → uploaded files missing on another worker
Redis Sentinel/Cluster	Recommended	Single Redis failure causes full service downtime
Same timezone (TZ)	Required	Schedule/audit log time inconsistency

Alembic migration conflicts are auto-resolved by lock in the latest version, but serializing container start order (e.g., wait for first worker’s healthcheck to pass before starting others) is safer.

Health Endpoints (Monitoring Integration)

Cloosphere provides health endpoints integrable with external monitoring (Prometheus, Datadog, Azure Monitor, etc.).

Endpoint	Use	Auth
`GET /health`	Basic liveness check	None
`GET /health/db`	DB connection state (503 + error detail if down)	None
`GET /health/redis`	Redis ping (503 if unavailable)	None
`GET /health/full`	DB + Redis + TaskQueue overall state	Admin

Response example:

GET /health/full

{
  "status": "ok",
  "components": {
    "database": { "status": "ok", "latency_ms": 12 },
    "redis": { "status": "ok", "latency_ms": 1 },
    "task_queue": { "status": "ok", "pending": 3 }
  }
}

The admin panel’s System Diagnostics panel shows /health/full results in GUI. Recommend /health/db for CI/CD readiness probe and /health for liveness probe.

Operations Checklist (Summary)

Pre-deploy verification:

Verify public URL

Is CLOOSPHERE_PUBLIC_URL set to an external HTTPS FQDN?

DB / Redis

DATABASE_URL connects normally; REDIS_URL required for multi-worker

OIDC (optional)

For SSO, set OPENID_PROVIDER_URL + client credentials

Teams Bot (optional)

For Teams integration, register Azure Bot Service + upload manifest

AGE pool size

Adjust AGE_POOL_MAX per KG usage scale

Health monitoring

Add /health/db, /health/redis polling to external monitoring

Audit log activation

Verify the license includes the audit_log feature → Audit Log

Backup policy

PostgreSQL + file storage periodic backups, AGE graph backup cadence configured

General Settings

GUI-managed authentication and feature toggles

Teams Bot

Microsoft Teams integration

Notification Settings

Email and webhook notification channels

Troubleshooting

Common issues and solutions in operations

​Required Environment Variables

​Public URL

​Database / Redis

​Knowledge Graph (AGE)

​SSO / OIDC Integration (optional)

​Teams Bot (optional)

​Multi-Worker Operations Checklist

​Health Endpoints (Monitoring Integration)

​Operations Checklist (Summary)

​Related Pages

General Settings

Teams Bot

Notification Settings

Troubleshooting

Required Environment Variables

Public URL

Database / Redis

Knowledge Graph (AGE)

SSO / OIDC Integration (optional)

Teams Bot (optional)

Multi-Worker Operations Checklist

Health Endpoints (Monitoring Integration)

Operations Checklist (Summary)

Related Pages