On this page

Deploy over HTTPS

Download and verify the release

Start Docker on the server with Compose 2.24.4 or later. Once a stable release is published, download contextbase-compose.tar.gz and contextbase-compose.tar.gz.sha256 from the same GitHub release. In the directory with both files, verify and extract the archive.

sha256sum -c contextbase-compose.tar.gz.sha256 &&
  mkdir contextbase-release &&
  tar -xzf contextbase-compose.tar.gz -C contextbase-release &&
  cd contextbase-release

On macOS, use shasum -a 256 -c in place of sha256sum -c.

Create the administrator before opening public access

From the extracted directory, start the release on the server’s loopback interface. Compose pulls the pinned images.

export CONTEXTBASE_PLATFORM="$(cat PLATFORM)"
docker compose --project-name contextbase-server \
  -f compose.yaml -f compose.images.yaml \
  up --no-build --pull missing -d --wait

From the operator workstation, open a tunnel and leave it running.

ssh -N -L 127.0.0.1:13000:127.0.0.1:13000 user@server

Open http://localhost:13000/setup on the workstation and create the administrator. Change both ports in the tunnel command and the browser URL if you configured a different gateway port.

Enable HTTPS

After creating the administrator, point the domain at the server and make ports 80 and 443 reachable for Caddy’s certificate challenge. If the gateway must stay private, configure a trusted certificate in the included docker/caddy/server-example.Caddyfile. Set CONTEXTBASE_DOMAIN to your DNS name and run from the same extracted directory. Caddy certificate challenges.

export CONTEXTBASE_PLATFORM="$(cat PLATFORM)"
export CONTEXTBASE_DOMAIN=contextbase.example.com
docker compose --project-name contextbase-server \
  -f compose.yaml -f compose.images.yaml -f compose.server.yaml \
  up --no-build --pull missing -d --wait

Open https://contextbase.example.com and sign in with the account you already created. For ps, logs and later updates, use the same project name, environment variables and Compose files. Keep direct access to the backend, database, broker and original-file store on private networks.

Control startup and browser origins

Keep the UI and API on one HTTPS origin when possible. Caddy sends API, admin, health, API reference, MCP and OAuth requests to Django, serves static assets, and forwards other requests to the frontend. The shared gateway routes define those boundaries. Originals are served through the authorized download endpoint.

For a separate frontend host, use HTTPS on both origins. Set FRONTEND_ORIGINS to a comma-separated list of exact frontend origins (scheme, host and optional port) and AUTH_REFRESH_COOKIE_SAMESITE=none. The same list configures CORS and the trusted cookie request origins. The cookie requires the Secure flag in this mode. When a CDN or load balancer precedes Caddy, configure both Caddy’s trusted proxies and TRUSTED_PROXY_COUNT for the real chain.

The production services include one-shot migrate and assets steps. With Compose, check that they exit successfully before opening traffic. If the orchestrator ignores depends_on, run these steps explicitly once per rollout, then start or replace the application replicas. Keep the code, database schema, assets and workers on compatible revisions. The assets step collects static files into a shared volume.

Protect credentials and persistent state

The release generates its keys in the configuration volume. Back up this volume together with the database and originals. Changing the configuration encryption key independently can make saved provider credentials unreadable.

Create narrowly scoped API keys and store provider credentials on the server. Keep private environment files and backup archives out of source control and support bundles. See spaces and access for user and machine grants. Use the repository’s security reporting guide to report a vulnerability.

Resource and connection planning

To estimate database demand, replace up and its options in the same Compose command with exec web python manage.py connection_budget --processes 8. Replace 8 with the number of processes that share the database across replicas. Count each web worker, each Celery worker child and the scheduler.

The release’s default embedding model is BGE-M3 on CPU. The first use may download its weights. The model-cache volume can be regenerated, but a cold cache raises first-start or first-request time. Image size, model cache, database, originals and temporary processing each consume disk separately.

The documented reference run used Linux/amd64 containers on Docker Desktop with about 32 GiB visible to its VM. See the test conditions in the resource measurements. Measure representative operations and concurrent users before choosing production resource limits.

Application connections use PgBouncer in session mode. In the packaged setup the ordinary endpoint is pgbouncer:6432. Migrations and administrative tasks use the primary, normally db:5432. A PgBouncer outage does not switch the application to the primary. The packaged defaults are 100 PostgreSQL connection slots, a 64-backend budget for the platform role, and a declared 16-slot administrative reserve checked by preflight. PgBouncer accepts up to 512 clients by default. Diagnose the backend budget with SHOW POOLS, SHOW STATS and PostgreSQL’s pg_stat_activity, since many clients can wait for fewer backends.

Set PostgreSQL database encoding to UTF8 and verify it on an existing installation before admitting writes. One-time cluster initialization arguments do not convert an existing volume. For encoding or locale changes, restore into a separate compatible cluster and verify both ordinary and multilingual data, including JSON fields.

Add external services deliberately

The starter’s local extractor processes supported UTF-8 uploads. For PDF, Office documents and OCR, configure the separate HTTP extractor using EXTRACTOR_BACKEND=http, EXTRACTOR_SERVICE_URL and EXTRACTOR_API_KEY. Verify that the address is reachable from the API and worker containers. A container’s localhost points at itself. See processing and indexing for the formats and storage connections for vector database choices.

To run embedding models on a GPU, deploy a separate OpenAI-compatible endpoint and register the model in ContextBase. Check that the API and worker can reach the endpoint after the weights load, and measure process and device memory. Choose the model when creating a new Space. To change the model or vector representation for an existing corpus, plan to reindex it in a new Space. Generation uses a configured LLM endpoint with its own capacity and readiness checks.

Configure the outbound route

In a Space you own, open Settings → Outbound route to route supported outgoing connections, including language model calls, through a proxy. Enter a scheme, host, and optional port, for example http://proxy.internal:3128. The accepted schemes are http, https, socks5, and socks5h. SOCKS requires support in the server’s HTTP client. Enter proxy credentials in their own fields. A blank password during an update keeps the stored password.

Save route checks the proposed configuration before saving it. If the check blocks the change, the previous route stays in place. After saving, the form checks the proxy again. Then test a call to the configured model. Clear route restores inheritance from the installation. Set the installation default with OUTBOUND_PROXY_URL, OUTBOUND_PROXY_USERNAME, and OUTBOUND_PROXY_PASSWORD in the server environment. A Space override replaces that whole proxy configuration.

ContextBase0.1.0

Search the documentation