swadhin / opencodehub-docs public
/ opencodehub-docs / src / content / docs / administration / configuration.md
swadhinbiswas fix: remove highlight.js CSS import causing Docker build failure · 7/21/2026
eeb5038
216 lines · 7.9 KB
Raw Download

title: "Configuration Reference"

OpenCodeHub is configured via environment variables. Copy .env.example to .env and edit.

Server

Variable Description Default
HOST Bind address 0.0.0.0
PORT HTTP port 4321
SITE_URL Public URL of the instance http://localhost:4321
APP_NAME Instance name OpenCodeHub
NODE_ENV development or production development

Database

Variable Description Default
DATABASE_DRIVER postgres, sqlite, or turso (LibSQL) postgres
DATABASE_URL Connection string —
DATABASE_POOL_SIZE Connection pool size 10
DATABASE_SSL Enable PostgreSQL SSL false
DATABASE_AUTH_TOKEN Auth token (Turso/LibSQL only) —

:::caution[Production]
PostgreSQL is required for production. All schemas use pgTable. SQLite is for development only.
:::

Redis

Variable Description Default
REDIS_URL Redis connection string redis://localhost:6379
REDIS_PASSWORD Redis password —

Redis is required in production for distributed locking, rate limiting, and sessions. For edge deployments (Vercel), use Upstash Redis with UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

Authentication

Variable Description Generate With
JWT_SECRET Signs auth tokens openssl rand -base64 32
JWT_EXPIRES_IN Token expiry 7d
SESSION_SECRET Signs session cookies openssl rand -base64 32

Security Secrets

All secrets below must be unique. Generate each with openssl rand -hex 32.

Variable Purpose
INTERNAL_HOOK_SECRET Secures git hook communication between Git server and app
CRON_SECRET Protects cron endpoints (GC, mirror sync, notification digests)
AI_CONFIG_ENCRYPTION_KEY Encrypts AI provider API keys at rest
WORKFLOW_SECRET_ENCRYPTION_KEY Encrypts CI/CD workflow secrets at rest
RUNNER_SECRET Shared secret between server and CI runners

OAuth Providers

Variable Description
OAUTH_GOOGLE_CLIENT_ID Google OAuth client ID
OAUTH_GOOGLE_CLIENT_SECRET Google OAuth client secret
OAUTH_GITHUB_CLIENT_ID GitHub OAuth client ID
OAUTH_GITHUB_CLIENT_SECRET GitHub OAuth client secret
OAUTH_GITLAB_CLIENT_ID GitLab OAuth client ID
OAUTH_GITLAB_CLIENT_SECRET GitLab OAuth client secret

OpenCodeHub also supports SSO via SAML and OIDC. Configure these through the admin dashboard.

Git Configuration

Variable Description Default
GIT_REPOS_PATH Directory for git repositories ./data/repositories
GIT_SSH_PORT SSH git server port 2222
GIT_SSH_HOST_KEY Path to SSH host key ./data/ssh/host_key

Storage

Variable Description Default
STORAGE_TYPE local or s3 local
STORAGE_PATH Local storage path ./data/storage

S3-Compatible Storage

Works with AWS S3, MinIO, Cloudflare R2, Garage, SeaweedFS, Ceph RGW, Wasabi, Backblaze B2, and any S3-compatible service.

Variable Description
STORAGE_BUCKET Bucket name (required for S3)
STORAGE_REGION S3 region (default: us-east-1)
STORAGE_ENDPOINT Custom S3 endpoint (for MinIO, R2, etc.)
STORAGE_ACCESS_KEY_ID S3 access key
STORAGE_SECRET_ACCESS_KEY S3 secret key

:::tip[Performance]
For best performance, use local SSD storage. Object storage (S3/R2) introduces latency. Use S3 for multi-node deployments or backup.
:::

CI/CD Runner

Variable Description Default
RUNNER_ENABLED Enable the CI runner true
RUNNER_DOCKER_SOCKET Docker socket path /var/run/docker.sock
RUNNER_WORKSPACE_PATH Workspace directory ./data/runner/workspaces
RUNNER_ARTIFACTS_PATH Artifacts directory ./data/runner/artifacts
RUNNER_CONCURRENT_JOBS Max concurrent jobs 2
RUNNER_TIMEOUT Job timeout in seconds 3600
RUNNER_REGISTRATION_TOKEN_TTL_DAYS Token TTL 90

Email (SMTP)

Variable Description Default
SMTP_HOST SMTP hostname —
SMTP_PORT SMTP port 587
SMTP_USER SMTP username —
SMTP_PASSWORD SMTP password —
SMTP_FROM From address [email protected]

Logging

Variable Description Default
LOG_LEVEL debug, info, warn, error info
LOG_FILE Log file path ./data/logs/opencodehub.log

Rate Limiting

Variable Description Default
RATE_LIMIT_ENABLED Enable rate limiting true
RATE_LIMIT_AUTH Auth endpoints (req/15min) 5
RATE_LIMIT_API API endpoints (req/min) 100
RATE_LIMIT_GIT Git operations (req/min) 200
RATE_LIMIT_GENERAL General endpoints (req/min) 60
RATE_LIMIT_SKIP_DEV Skip in development false
CSRF_SKIP_DEV Skip CSRF in development false

CORS & Request Limits

Variable Description Default
ALLOWED_ORIGINS Comma-separated allowed origins http://localhost:4321
MAX_REQUEST_BODY_MB Max request body size (MB) 10
MAX_PACK_SIZE_MB Max git pack size (MB) 500
GIT_PROCESS_TIMEOUT_SECS Git process timeout (sec) 300

Feature Flags

Variable Description Default
ENABLE_REGISTRATION Allow new user signups true
ENABLE_WIKI Enable repository wikis true
ENABLE_ISSUES Enable issue tracking true
ENABLE_ACTIONS Enable CI/CD pipelines true
ENABLE_PACKAGES Enable package registry false
ENABLE_AI_ASSISTANT Enable AI code review true

AI Providers

Configure one or more AI providers for code review. Keys are encrypted at rest using AI_CONFIG_ENCRYPTION_KEY.

Variable Provider
OPENAI_API_KEY OpenAI (GPT-4, GPT-4o)
ANTHROPIC_API_KEY Anthropic (Claude)
GROQ_API_KEY Groq (fast inference)
BYTEZ_API_KEY Bytez
OPENROUTER_API_KEY OpenRouter (multi-model)
TOGETHER_API_KEY Together AI
GOOGLE_AI_API_KEY Google AI (Gemini)

Ollama is supported for local/self-hosted AI. No API key required — just set the Ollama endpoint in the admin dashboard.

External Review Agent

Variable Description
EXTERNAL_AGENT_WEBHOOK_URL Webhook URL for external AI agent
EXTERNAL_AGENT_API_KEY API key for the external agent
EXTERNAL_AGENT_CALLBACK_SECRET Callback verification secret

Backup

Variable Description Default
BACKUP_ENCRYPTION_KEY Encryption key for backups —
BACKUP_S3_BUCKET S3 bucket for backups —
BACKUP_S3_PREFIX S3 prefix opencodehub-backups
BACKUP_RETENTION_DAYS Retention period 30
BACKUP_DIR Local backup directory ./backups

Air-gapped Mode

Variable Description Default
AIR_GAPPED_MODE Disable all external API calls false

When enabled, OpenCodeHub operates fully offline. AI features are disabled unless you run a local model (e.g., Ollama).

Observability

Variable Description
GRAFANA_OTLP_ENDPOINT Grafana Cloud OTLP endpoint
GRAFANA_INSTANCE_ID Grafana Cloud instance ID
GRAFANA_API_KEY Grafana Cloud API key

OpenCodeHub exports OpenTelemetry traces and Prometheus metrics. See Monitoring for setup details.