Environment Variables

All configuration is provided to OpenCLM via environment variables. Copy .env.example to .env and fill in your values before starting the stack.

API Server Variables

Variable	Required	Default	Description
`DATABASE_URL`	✅	—	PostgreSQL connection string: `postgresql://user:pass@host:5432/dbname`
`JWT_SECRET`	✅	—	At least 32 random characters. Used to sign access tokens
`APP_URL`	✅	—	The public URL of your OpenCLM instance (e.g. `https://openclm.yourcompany.com`)
`PORT`	❌	`4000`	API server listen port
`NODE_ENV`	❌	`production`	Set to `development` to enable verbose logging
`LOG_LEVEL`	❌	`info`	Log verbosity: `error`, `warn`, `info`, `debug`
`CORS_ORIGINS`	❌	`APP_URL`	Comma-separated list of allowed CORS origins
`MAX_FILE_SIZE_MB`	❌	`25`	Maximum file upload size in megabytes
`SESSION_TIMEOUT_MINUTES`	❌	`60`	Minutes of inactivity before session expires

Variable	Required	Default	Description
`POSTGRES_USER`	✅	—	PostgreSQL username
`POSTGRES_PASSWORD`	✅	—	PostgreSQL password
`POSTGRES_DB`	✅	—	PostgreSQL database name
`POSTGRES_HOST`	❌	`db`	PostgreSQL host (Docker service name or IP)
`POSTGRES_PORT`	❌	`5432`	PostgreSQL port

Variable	Required	Default	Description
`KEYCLOAK_URL`	✅	—	Keycloak server URL (e.g. `https://openclm.yourcompany.com/auth`)
`KEYCLOAK_REALM`	✅	`openclm`	Keycloak realm name
`KEYCLOAK_CLIENT_ID`	✅	`openclm-app`	Keycloak OIDC client ID
`KEYCLOAK_CLIENT_SECRET`	✅	—	Keycloak OIDC client secret
`KC_ADMIN_USER`	✅	—	Keycloak admin console username
`KC_ADMIN_PASSWORD`	✅	—	Keycloak admin console password

Variable	Required	Default	Description
`SMTP_HOST`	❌	—	SMTP server hostname
`SMTP_PORT`	❌	`587`	SMTP port
`SMTP_USER`	❌	—	SMTP username
`SMTP_PASS`	❌	—	SMTP password
`SMTP_FROM_NAME`	❌	`OpenCLM`	From display name in emails
`SMTP_FROM_EMAIL`	❌	—	From email address
`SMTP_SECURE`	❌	`true`	Use TLS/STARTTLS

If SMTP is not configured, email notifications are disabled and only in-app notifications are sent.

Variable	Required	Default	Description
`OPENSIGN_API_URL`	❌	—	OpenSign API base URL
`OPENSIGN_API_KEY`	❌	—	OpenSign API key

OpenSign can also be configured via the UI at Settings → Integrations.

Variable	Required	Default	Description
`VITE_API_URL`	✅	—	The public URL of the API (e.g. `https://openclm.yourcompany.com/api`)
`VITE_KEYCLOAK_URL`	✅	—	The public URL of Keycloak auth endpoint
`VITE_KEYCLOAK_REALM`	✅	`openclm`	Keycloak realm name
`VITE_KEYCLOAK_CLIENT_ID`	✅	`openclm-app`	Keycloak client ID

Store secrets in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Docker Secrets) rather than plain text .env files.
Never commit .env to version control — it is already in .gitignore.
Rotate JWT_SECRET and API keys periodically.
Use strong, randomly generated passwords for POSTGRES_PASSWORD and KC_ADMIN_PASSWORD.