Docker (Self-Hosted)
Deploy Pragence on one server with Docker Compose. This is the recommended path for a single-organization (single-tenant) installation.
Prerequisites
- Docker Engine 24+ and Docker Compose v2.24+
- A public hostname whose DNS record points at the server, with ports 80 and 443 open
- An API key for the LLM and embedding provider you choose
- Capacity and disk needs depend on the selected models, corpus, and workload.
Quick Start
Put docker-compose.yml from your release in a directory, and create .env next to it:
PRAGENCE_DOMAIN=pragence.example.edu
PRAGENCE_REGISTRY=<registry path from your release>
PRAGENCE_VERSION=<release tag>
DEPLOYMENT_MODE=self_hosted
ENVIRONMENT=production
LLM_PROVIDER=gemini
EMBEDDING_PROVIDER=gemini
GEMINI_API_KEY=<your key>
RERANKER_TYPE=noneThen start the stack:
docker compose up -d
docker compose ps
curl https://pragence.example.edu/health/readyIf you deploy through the Distr customer portal, it writes the same .env for you and runs these steps with its agent.
On first start, Pragence:
- Generates the database, orchestration, JWT and credential-encryption secrets and keeps them in Docker volumes. You never set a database password.
- Installs the database schema as the schema owner.
- Enables the restricted
pragence_appdatabase login that the API and workers use. It is not an owner, superuser or row-level-security bypass role, and the API refuses to start otherwise. - Starts the API, console and job worker, and obtains a TLS certificate for
PRAGENCE_DOMAIN.
The first person to register becomes the instance owner. Later self-service sign-ups are closed.
Configuration
| Variable | Required | Description |
|---|---|---|
PRAGENCE_DOMAIN | Yes | Public hostname. Caddy obtains and renews its certificate. |
PRAGENCE_REGISTRY / PRAGENCE_VERSION | Yes | Image registry path and release tag. |
DEPLOYMENT_MODE | Yes | self_hosted for customer installations. |
LLM_PROVIDER / provider key | Yes | Configure the selected LLM and embedding provider, such as GEMINI_API_KEY for the default Gemini provider or OPENAI_API_KEY when using OpenAI. |
RERANKER_TYPE | No | none, cohere or openrouter, with the matching API key. |
PRAGENCE_ENABLED_MODULES | No | Empty selects the required Knowledge capability; schema installation remains complete. |
Services
| Service | Published port | Description |
|---|---|---|
caddy | 80, 443 | HTTPS entry point for PRAGENCE_DOMAIN |
web | — | Console; proxies /api, /public and /media to the API |
app | — | Pragence API |
prefect-job-worker | — | Ingestion and connector jobs |
prefect-server / prefect-db | — | Durable job queue and run history |
postgres | — | PostgreSQL with pgvector and pg_textsearch |
redis | — | Cache |
Only Caddy is reachable from outside the server. To open the job dashboard, use an SSH tunnel to the prefect-server container.
Updating
Set PRAGENCE_VERSION to the new release, then:
docker compose pull
docker compose up -dThe schema step runs again before the API starts. On an installed schema it makes no changes.
Backups
Back up the database volume (or a pg_dump), the pragence_uploads and pragence_data volumes, and the three *_secrets volumes together. Integration credentials are encrypted with the generated key, so a database restored without its secret volumes cannot read them.
Logs
docker compose logs -f
docker compose logs -f app
docker compose logs -f postgres