Skip to main content

Deployment

Note: Comper is currently in private beta. To access the Docker image, you'll need to request a Docker Hub access token from us. Please contact us to get started.

Comper is fully multi-tenant: multiple boards can run on the same server instance. However, each board instance is hosted on a single server (not horizontally scalable by design). This means that while a single Comper server can host many boards, an individual board cannot be distributed across multiple servers.

Runtime Shape​

  • Single web server (default port 8001) serves:
    • The API
    • WebSockets
    • The built frontend SPA from frontend/dist (static middleware + SPA fallback to index.html)
  • Background work runs in-process using Loco workers + a Postgres-backed queue.
  • Local storage path is used for runtime storage (STORAGE_PATH, default /comper/storage).
  • Postgres database is required for core persistence and the background queue (DATABASE_URL).

Configuration​

Core Environment Variables​

  • FRONTEND_URL (required; also used for OAuth redirect URLs and links)
  • JWT_SECRET (required; JWT auth enabled, 7-day expiration configured)
  • MAX_CPU_THREADS (0 = auto-detect)
  • REQUEST_TIMEOUT_SECONDS
  • LOG_FORMAT (compact/pretty/json)

Database & Queue (Postgres)​

  • DATABASE_URL (used for both DB and queue)
  • WORKERS (queue concurrency)
  • DB pool sizing via DB_MIN_CONNECTIONS / DB_MAX_CONNECTIONS and timeouts

Email​

  • SMTP_HOST, SMTP_PORT, SMTP_SECURE, optional SMTP_USER/SMTP_PASSWORD
  • SMTP_FROM

Sentry​

  • SENTRY_DSN, SENTRY_ENVIRONMENT

Authentication Modes​

Authentication is configured via feature flags:

  • Password auth: PASSWORDS_ENABLED=true
  • OAuth providers are enabled when their credentials are present:
    • Google: GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET
    • GitHub: GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET
    • Microsoft: MICROSOFT_OAUTH_CLIENT_ID / MICROSOFT_OAUTH_CLIENT_SECRET / MICROSOFT_OAUTH_TENANT_ID
  • SAML: SAML_ENABLED=true plus SAML-specific settings (SAML_IDP_METADATA_PATH, SAML_SP_ENTITY_ID, SAML_SP_ACS_URL, SAML_PROVIDER)

Why Boards Are Not Horizontally Scalable​

While Comper is fully multi-tenant (multiple boards can share a server), each board instance is hosted on a single server and cannot be distributed across multiple servers. This design choice enables:

  • WebSocket presence/collaboration with a single coordination point per board.
  • Local filesystem storage (e.g. STORAGE_PATH) and RocksDB cache usage (instance-local, optimized for fast access).
  • In-process worker execution with a single application runtime coordinating work and UI updates for each board.

This architecture is optimized for single-server deployments where multiple boards can coexist efficiently on the same instance.

Docker Image Access​

The Comper Docker image is hosted on Docker Hub under comperio/comper. To access it, you'll need:

  1. Request an access token - Contact us to receive a Docker Hub token

  2. Login to Docker Hub:

    docker login -u comperio

    Use the token provided to you when prompted for the password.

  3. Pull the image:

    docker pull comperio/comper:latest

Kubernetes Deployment​

Note: The Helm chart is currently in beta and has been contributed to Comper by one of our early adopters. Please report any issues or improvements via GitHub.

Comper provides a Helm chart for easy deployment to Kubernetes clusters.

Download the Helm Chart​

Download the Helm chart:

After downloading:

# Extract the zip file
unzip comper-helm-chart.zip

# Navigate to the chart directory
cd helm-chart

Installing with Helm​

  1. Install the chart using the local chart directory:

    helm install comper ./helm-chart

  2. Customize configuration by creating a values.yaml file with your settings:

    helm install comper ./helm-chart -f my-values.yaml

  3. Upgrade an existing installation:

    helm upgrade comper ./helm-chart -f my-values.yaml

Helm Chart Configuration​

The Helm chart supports all configuration options available via environment variables. Key sections include:

  • Authentication: Password auth, OAuth (Google, GitHub, Microsoft), and SAML
  • Database: PostgreSQL connection settings
  • SMTP: Email configuration
  • Resources: CPU and memory limits
  • Ingress: Kubernetes ingress configuration
  • Storage: Persistent volume configuration

See the SAML & OIDC Setup guide for authentication configuration details.

Backend Functionality​

Beyond what is exposed via the UI, the backend also:

  • Parses git repositories, groups content by language, and stores computed results in a RocksDB cache for fast retrieval.