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.