Pragence

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=none

Then start the stack:

docker compose up -d
docker compose ps
curl https://pragence.example.edu/health/ready

If 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:

  1. Generates the database, orchestration, JWT and credential-encryption secrets and keeps them in Docker volumes. You never set a database password.
  2. Installs the database schema as the schema owner.
  3. Enables the restricted pragence_app database 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.
  4. 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

VariableRequiredDescription
PRAGENCE_DOMAINYesPublic hostname. Caddy obtains and renews its certificate.
PRAGENCE_REGISTRY / PRAGENCE_VERSIONYesImage registry path and release tag.
DEPLOYMENT_MODEYesself_hosted for customer installations.
LLM_PROVIDER / provider keyYesConfigure the selected LLM and embedding provider, such as GEMINI_API_KEY for the default Gemini provider or OPENAI_API_KEY when using OpenAI.
RERANKER_TYPENonone, cohere or openrouter, with the matching API key.
PRAGENCE_ENABLED_MODULESNoEmpty selects the required Knowledge capability; schema installation remains complete.

Services

ServicePublished portDescription
caddy80, 443HTTPS 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 -d

The 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

On this page