Install Xberg Pro with Docker Compose
Xberg Pro runs as one container that serves the REST API on port 8080, the bundled web console on port 3000 and Prometheus metrics on port 9090. PostgreSQL is the only other service. Documents and results go to local disk by default, or to S3, GCS or Azure Blob Storage.
Use this page for a single host: an evaluation, a proof of concept or a small production deployment. For Kubernetes, use Install Xberg Pro with Helm.
The install has six steps. Each step ends with a check. Do not continue until the check passes.
- Get the install files
- Generate credentials
- Write the Compose file
- Start Pro
- Check the license
- Create a project and an API key
Prerequisites
Section titled “Prerequisites”- A Linux or macOS host with Docker Engine and the Compose plugin, plus
curl,jqand OpenSSL. - Helm 3.8 or newer, used once to download the install files. It needs no cluster.
- Disk for the
/datavolume. Model and result caches take about 20 GiB of it, and accepted documents and results are retained with the corpus. - A Pro license token from Xberg. Contact contact@xberg.io if you do not have one. See Licensing.
- Internet access to
ghcr.ioandus-central1-docker.pkg.dev. Both are public and need no login. The container refuses to start without a valid license.
The Pro image is published for linux/amd64 and linux/arm64.
1. Get the install files
Section titled “1. Get the install files”You do not need access to any private repository. The Pro Helm chart is public, and its archive carries the database bootstrap script and SQL that the Compose stack mounts. The same chart release also names the image digest that matches those files.
Download the chart and look up the image. Set VERSION to the chart release you were given, or to the latest published release. The example uses 0.7.4:
export VERSION=0.7.4mkdir xberg-pro && cd xberg-prohelm pull oci://us-central1-docker.pkg.dev/xberg-public-assets/helm-charts/pro \ --version "$VERSION" --untarexport PRO_CHART_DIR="$PWD/pro"helm show values "$PRO_CHART_DIR" | sed -n '/^image:/,/^imagePullSecrets:/p'Set PRO_IMAGE to the repository and digest that the output shows:
export PRO_IMAGE="REPLACE_WITH_REPOSITORY@REPLACE_WITH_DIGEST"Copy the bootstrap files into the working directory. The Compose file mounts scripts/ as the bootstrap script directory and sql/ as the schema directory:
mkdir -p scripts sqlcp "$PRO_CHART_DIR"/charts/_distribution/files/pro-db-bootstrap.sh scripts/cp "$PRO_CHART_DIR"/charts/_distribution/files/*.sql sql/The chart archive does not carry the small script that turns on vector-index processing after the first start, because the Helm chart does that in a hook. Create it for Compose. Expand the block, copy it as is and do not edit it:
Create scripts/pro-db-claims-enable.sh
cat > scripts/pro-db-claims-enable.sh <<'SCRIPT'#!/bin/shset -eu
physical_migration_role=xberg_physical_migration_login
: "${POSTGRES_DB:?POSTGRES_DB is required}": "${POSTGRES_PHYSICAL_MIGRATION_PASSWORD:?POSTGRES_PHYSICAL_MIGRATION_PASSWORD is required}"
PGPASSWORD="$POSTGRES_PHYSICAL_MIGRATION_PASSWORD" \ PGOPTIONS='-c role=xberg_vector_index_activation_admin' \ psql --set=ON_ERROR_STOP=1 --username "$physical_migration_role" --dbname "$POSTGRES_DB" <<'SQL'SELECT to_regrole('xberg_vector_index_activation_admin') IS NOT NULL AS activation_role_exists\gset\if :activation_role_exists SELECT to_regprocedure( 'vector_control.set_vector_index_ddl_worker_claims_enabled(boolean)' ) IS NOT NULL AS setter_exists \gset \if :setter_exists SELECT vector_control.set_vector_index_ddl_worker_claims_enabled(TRUE); \else DO $body$ BEGIN RAISE EXCEPTION 'vector index claims setter is missing'; END $body$; \endif\else DO $body$ BEGIN RAISE EXCEPTION 'vector index activation role is missing'; END $body$;\endifSQLSCRIPTchmod +x scripts/*.shThe script fails with a named error when its prerequisites are missing, which means the bootstrap and the image come from different releases.
Always take the bootstrap files from the chart release that matches the image you run. Mixing versions fails the schema checks at startup.
Check. The directories hold the files, and the image pulls:
ls scriptsls sql | wc -ldocker pull "$PRO_IMAGE"ls scripts lists pro-db-bootstrap.sh and pro-db-claims-enable.sh. The SQL count is 40 or more. The pull ends with Status: Downloaded or Image is up to date.
2. Generate credentials
Section titled “2. Generate credentials”Pro uses nine passwords: the administrator and eight runtime logins. Each login has narrow rights, so a leaked application credential cannot alter the schema. Generate all passwords once, the control-plane key and the optional integration keys into a protected env file. Export XBERG_LICENSE_KEY (the token, without a trailing newline) first, then run the command in a subshell so that its options do not stay in your terminal:
export XBERG_LICENSE_KEY=REPLACE_WITH_LICENSE_TOKEN( set -euC umask 077 { for role in ADMIN APPLICATION MAINTENANCE INDEX_WORKER VECTOR_BROKER \ MIGRATION SCHEMA_OWNER ROLE_ADMIN PHYSICAL_MIGRATION; do printf 'PRO_POSTGRES_%s_PASSWORD=%s\n' "$role" "$(openssl rand -hex 24)" done printf 'XBERG_ADMIN_KEY=kz_%s\n' "$(openssl rand -hex 24)" printf 'XBERG_LICENSE_KEY=%s\n' "$XBERG_LICENSE_KEY" printf 'PRO_IMAGE=%s\n' "$PRO_IMAGE" printf 'PRO_PULL_POLICY=missing\n' printf 'INTEGRATION_KEK=%s\n' "$(openssl rand -base64 32)" printf 'INTEGRATION_STATE_SECRET=%s\n' "$(openssl rand -base64 32)" } > .env.pro)The set -C option makes the command fail instead of overwriting an existing .env.pro. If the command fails part way, delete the partial file and run it again.
Keep this file and do not commit it. The nine passwords must stay the same across restarts, because the bootstrap service rotates the database roles to match them. XBERG_ADMIN_KEY cannot be recovered from the data volume.
INTEGRATION_KEK and INTEGRATION_STATE_SECRET enable the integration hub for every source connector, not only OAuth ones. Without them the hub answers 503. Set both or neither. Pro refuses to start with only one.
Check. The file holds nine passwords and the other values:
grep -c '^PRO_POSTGRES_.*_PASSWORD=' .env.progrep -c -E '^(XBERG_ADMIN_KEY|XBERG_LICENSE_KEY|PRO_IMAGE)=.+' .env.proThe first command prints 9 and the second prints 3.
3. Write the Compose file
Section titled “3. Write the Compose file”Save this as docker-compose.pro.yml. It starts PostgreSQL with pgvector, runs the one-shot db-bootstrap service that creates roles and applies the schema, then starts Pro. The db-claims-enable service runs once after Pro is ready:
services: postgres: image: pgvector/pgvector:pg18 environment: POSTGRES_USER: xberg POSTGRES_PASSWORD: "${PRO_POSTGRES_ADMIN_PASSWORD:?Set PRO_POSTGRES_ADMIN_PASSWORD}" POSTGRES_DB: xberg POSTGRES_APPLICATION_PASSWORD: "${PRO_POSTGRES_APPLICATION_PASSWORD:?Set PRO_POSTGRES_APPLICATION_PASSWORD}" POSTGRES_MAINTENANCE_PASSWORD: "${PRO_POSTGRES_MAINTENANCE_PASSWORD:?Set PRO_POSTGRES_MAINTENANCE_PASSWORD}" POSTGRES_INDEX_WORKER_PASSWORD: "${PRO_POSTGRES_INDEX_WORKER_PASSWORD:?Set PRO_POSTGRES_INDEX_WORKER_PASSWORD}" POSTGRES_VECTOR_BROKER_PASSWORD: "${PRO_POSTGRES_VECTOR_BROKER_PASSWORD:?Set PRO_POSTGRES_VECTOR_BROKER_PASSWORD}" POSTGRES_MIGRATION_PASSWORD: "${PRO_POSTGRES_MIGRATION_PASSWORD:?Set PRO_POSTGRES_MIGRATION_PASSWORD}" POSTGRES_SCHEMA_OWNER_PASSWORD: "${PRO_POSTGRES_SCHEMA_OWNER_PASSWORD:?Set PRO_POSTGRES_SCHEMA_OWNER_PASSWORD}" POSTGRES_ROLE_ADMIN_PASSWORD: "${PRO_POSTGRES_ROLE_ADMIN_PASSWORD:?Set PRO_POSTGRES_ROLE_ADMIN_PASSWORD}" POSTGRES_PHYSICAL_MIGRATION_PASSWORD: "${PRO_POSTGRES_PHYSICAL_MIGRATION_PASSWORD:?Set PRO_POSTGRES_PHYSICAL_MIGRATION_PASSWORD}" PRO_DB_INITIALIZE_SCHEMA: "true" PRO_DB_DEFER_CLAIMS_ENABLE: "true" healthcheck: test: ["CMD-SHELL", "pg_isready -U xberg -d xberg -h 127.0.0.1 -p 5432"] interval: 5s timeout: 3s retries: 15 volumes: - ./scripts/pro-db-bootstrap.sh:/docker-entrypoint-initdb.d/00-pro-db-bootstrap.sh:ro - ./sql:/schema:ro - postgres-socket:/var/run/postgresql
db-bootstrap: image: pgvector/pgvector:pg18 user: postgres network_mode: none read_only: true tmpfs: - /tmp:rw,noexec,nosuid,nodev,size=16m cap_drop: [ALL] security_opt: ["no-new-privileges:true"] depends_on: postgres: condition: service_healthy restart: "no" environment: PGHOST: /var/run/postgresql POSTGRES_USER: xberg POSTGRES_PASSWORD: "${PRO_POSTGRES_ADMIN_PASSWORD}" POSTGRES_DB: xberg POSTGRES_APPLICATION_PASSWORD: "${PRO_POSTGRES_APPLICATION_PASSWORD}" POSTGRES_MAINTENANCE_PASSWORD: "${PRO_POSTGRES_MAINTENANCE_PASSWORD}" POSTGRES_INDEX_WORKER_PASSWORD: "${PRO_POSTGRES_INDEX_WORKER_PASSWORD}" POSTGRES_VECTOR_BROKER_PASSWORD: "${PRO_POSTGRES_VECTOR_BROKER_PASSWORD}" POSTGRES_PHYSICAL_MIGRATION_PASSWORD: "${PRO_POSTGRES_PHYSICAL_MIGRATION_PASSWORD}" POSTGRES_SCHEMA_OWNER_PASSWORD: "${PRO_POSTGRES_SCHEMA_OWNER_PASSWORD}" POSTGRES_ROLE_ADMIN_PASSWORD: "${PRO_POSTGRES_ROLE_ADMIN_PASSWORD}" POSTGRES_MIGRATION_PASSWORD: "${PRO_POSTGRES_MIGRATION_PASSWORD}" PRO_DB_INITIALIZE_SCHEMA: "false" PRO_DB_DEFER_CLAIMS_ENABLE: "true" entrypoint: ["/bootstrap/pro-db-bootstrap.sh"] volumes: - ./scripts:/bootstrap:ro - ./sql:/schema:ro - postgres-socket:/var/run/postgresql
pro: image: ${PRO_IMAGE:?Set PRO_IMAGE to the image digest from the chart} pull_policy: ${PRO_PULL_POLICY:-missing} stop_grace_period: "3720s" depends_on: db-bootstrap: condition: service_completed_successfully environment: DATABASE_URL: "postgres://xberg_app:${PRO_POSTGRES_APPLICATION_PASSWORD}@postgres:5432/xberg" MAINTENANCE_DATABASE_URL: "postgres://xberg_maintenance_login:${PRO_POSTGRES_MAINTENANCE_PASSWORD}@postgres:5432/xberg" VECTOR_INDEX_BROKER_DATABASE_URL: "postgres://xberg_vector_index_broker_login:${PRO_POSTGRES_VECTOR_BROKER_PASSWORD}@postgres:5432/xberg" VECTOR_INDEX_QUEUE_DATABASE_URL: "postgres://xberg_index_worker_login:${PRO_POSTGRES_INDEX_WORKER_PASSWORD}@postgres:5432/xberg" VECTOR_INDEX_WORKER_LOGIN: xberg_index_worker_login VECTOR_INDEX_MIGRATION_LOGIN: xberg_schema_migrator VECTOR_INDEX_BROKER_LOGIN: xberg_vector_index_broker_login VECTOR_INDEX_PHYSICAL_MIGRATION_LOGIN: xberg_physical_migration_login MAINTENANCE_DB_POOL_SIZE: "16" PRO_BIND_ADDR: 0.0.0.0:8080 PRO_METRICS_ADDR: 0.0.0.0:9090 LOG_LEVEL: info STORAGE_PROVIDER: fs STORAGE_BUCKET: xberg STORAGE_FS_ROOT: /data/xberg PRO_MAX_CONCURRENCY: "4" PRO_MAX_UPLOAD_BYTES: "104857600" PRO_SHUTDOWN_DRAIN_SECS: "30" SESSION_COOKIE_SECURE: "${SESSION_COOKIE_SECURE:-true}" CACHE_ENABLED: "true" CACHE_DIR: /data/xberg-cache CACHE_MAX_BYTES: "10737418240" CACHE_TTL_SECS: "604800" XBERG_VECTORSTORE_DEFAULT_INDEX_METHOD: hnsw HF_HOME: /data/hf XBERG_RAG_WARMUP_ENABLED: "false" XBERG_EMBEDDING_ENGINE_CACHE_MAX_RESIDENT: "2" XBERG_RERANKER_ENGINE_CACHE_MAX_RESIDENT: "2" INTEGRATION_KEK: "${INTEGRATION_KEK:-}" INTEGRATION_STATE_SECRET: "${INTEGRATION_STATE_SECRET:-}" PRO_INTEGRATION_SYNC_ENABLED: "${PRO_INTEGRATION_SYNC_ENABLED:-false}" PRO_INTEGRATION_SYNC_CURSOR_KEY: "${PRO_INTEGRATION_SYNC_CURSOR_KEY:-}" SFTP_HOST_ALLOWLIST: "${SFTP_HOST_ALLOWLIST:-}" PRO_AUTH_MODE: "${PRO_AUTH_MODE:-required}" XBERG_DATA_POLICY: "${XBERG_DATA_POLICY:-standard}" XBERG_ADMIN_KEY: "${XBERG_ADMIN_KEY:-}" XBERG_LICENSE_KEY: "${XBERG_LICENSE_KEY:-}" ports: - "127.0.0.1:${PRO_WEB_PORT:-3000}:3000" - "127.0.0.1:${PRO_HTTP_PORT:-8080}:8080" - "127.0.0.1:${PRO_METRICS_PORT:-9090}:9090" read_only: true cap_drop: [ALL] security_opt: ["no-new-privileges:true"] tmpfs: - /tmp:rw,noexec,nosuid,nodev,size=64m volumes: - xberg-data:/data healthcheck: test: - CMD - node - -e - >- const urls = ['http://127.0.0.1:8080/readyz', 'http://127.0.0.1:9091/readyz', 'http://127.0.0.1:9092/readyz']; Promise.all(urls.map((u) => fetch(u).then((r) => { if (!r.ok) throw new Error(u + ' ' + r.status); }))) .then(() => process.exit(0), (e) => { console.error(String(e)); process.exit(1); }); interval: 10s timeout: 5s retries: 3 start_period: 120s
db-claims-enable: image: pgvector/pgvector:pg18 user: postgres network_mode: none read_only: true tmpfs: - /tmp:rw,noexec,nosuid,nodev,size=16m cap_drop: [ALL] security_opt: ["no-new-privileges:true"] depends_on: pro: condition: service_healthy restart: "no" environment: PGHOST: /var/run/postgresql POSTGRES_DB: xberg POSTGRES_PHYSICAL_MIGRATION_PASSWORD: "${PRO_POSTGRES_PHYSICAL_MIGRATION_PASSWORD}" entrypoint: ["/bootstrap/pro-db-claims-enable.sh"] volumes: - ./scripts:/bootstrap:ro - postgres-socket:/var/run/postgresql
volumes: xberg-data: postgres-socket:The health check probes /readyz on three ports: 8080 for the API, 9091 for the embedded extraction worker and 9092 for the vector-index broker. Ports 9091 and 9092 stay inside the container.
Ports bind to the loopback address on purpose. A published Docker port bypasses the host firewall, so put a TLS reverse proxy in front of 8080 and 3000 before you expose Pro. The default fs storage provider writes to the xberg-data volume. To use object storage instead, see Configuration.
Check. Compose accepts the file and resolves every variable:
docker compose --env-file .env.pro -f docker-compose.pro.yml config --quiet && echo OKThe command prints OK. A message that starts with required variable names a value missing from .env.pro.
4. Start Pro
Section titled “4. Start Pro”Start the stack and wait for the readiness check, then enable the vector-index claims that the bootstrap deferred. The second command runs once after every fresh up:
docker compose --env-file .env.pro -f docker-compose.pro.yml up --detach --wait prodocker compose --env-file .env.pro -f docker-compose.pro.yml run --rm --no-deps db-claims-enableOn a new volume, the PostgreSQL init hook creates the roles and applies the schema before Pro starts. The first start also pulls the image and can take a few minutes.
For a plain-HTTP evaluation on one machine, add SESSION_COOKIE_SECURE=false to .env.pro. Keep the default true for any TLS deployment.
Check. The pro service is healthy and answers on its probes:
docker compose --env-file .env.pro -f docker-compose.pro.yml ps procurl --fail http://localhost:8080/healthzcurl --fail http://localhost:8080/readyzcurl --fail http://localhost:9090/metrics | head -n 5ps shows healthy. /healthz reports that the process is alive. /readyz also checks PostgreSQL, the object store and the embedded vector-index worker, and answers 503 until each responds. Use /readyz for load-balancer and orchestrator checks.
If Pro does not become healthy, read the log:
docker compose --env-file .env.pro -f docker-compose.pro.yml logs pro | tail -n 305. Check the license
Section titled “5. Check the license”Pro verifies XBERG_LICENSE_KEY locally against the signing key baked into the image. No network call is involved, so air-gapped hosts are licensed the same way. Without a verifiable token Pro exits with code 78 and the Compose health check never passes.
Check. Read the license state with the admin key:
export XBERG_ADMIN_KEY=$(grep '^XBERG_ADMIN_KEY=' .env.pro | cut -d= -f2-)curl --fail -H "Authorization: Bearer $XBERG_ADMIN_KEY" http://localhost:8080/v1/licenseThe response reports the licensee, plan, expiry, grace window and days remaining. See Licensing for renewal and the grace period.
6. Create a project and an API key
Section titled “6. Create a project and an API key”Pro keeps work in projects, and API keys belong to a project. Use the admin key to create the first project:
export XBERG_URL=http://localhost:8080
export PROJECT_ID=$(curl -sX POST "$XBERG_URL/v1/projects" \ -H "Authorization: Bearer $XBERG_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Documents", "slug": "documents"}' | jq -r .id)echo "$PROJECT_ID"Then create a key for it:
export XBERG_API_KEY=$(curl -sX POST "$XBERG_URL/v1/projects/$PROJECT_ID/api-keys" \ -H "Authorization: Bearer $XBERG_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "ingest-service"}' | jq -r .key)The key field in the response is the full plaintext key and appears only once. Store it in your secret manager. See Projects and API keys for scopes, expiry and quotas.
Check. The key authenticates against the data plane:
curl --fail -H "Authorization: Bearer $XBERG_API_KEY" "$XBERG_URL/v1/usage"The response is a JSON usage report with total_documents set to 0. Continue with the quickstart.
Sign in to the web console
Section titled “Sign in to the web console”The web console listens on http://localhost:3000. Human sign-in needs an OpenID Connect (OIDC) identity provider. An API key cannot create a browser session. Choose one of three paths:
- API only. Skip the web console and call the REST API with
XBERG_ADMIN_KEYor a project key. No identity provider is needed. - OIDC sign-in. Register a public OIDC client with PKCE, then set
OIDC_ISSUER_URL,OIDC_AUDIENCE,JWT_SECRET, the threeNEXT_PUBLIC_OIDC_*values and an allowlist (PRO_ALLOWED_EMAILSorPRO_ALLOWED_EMAIL_DOMAINS). SetPRO_ADMIN_EMAILSto the people who manage the instance. No first user becomes admin automatically. Pro configuration lists every variable and gives a Compose override. - No authentication, evaluation only. Add
PRO_AUTH_MODE=disabledto.env.proand recreate the stack. The UI and API then use a single persisted local workspace without login or API key. Anyone who can reach the service can use it, so restrict network access.
Configuration
Section titled “Configuration”Compose sets the minimum Pro needs. Add other variables under the pro service’s environment: block, and recreate the service with up --detach pro. The common ones:
| Variable | Purpose |
|---|---|
STORAGE_PROVIDER, STORAGE_BUCKET |
fs (default), s3, gcs or azure, and the bucket or container name |
PRO_PUBLIC_API_URL |
The externally reachable origin of the API. Required for presigned uploads |
CORS_ALLOWED_ORIGINS |
Browser origins allowed to call the API. Empty sends no CORS headers |
PRO_MAX_CONCURRENCY |
Maximum concurrent extraction tasks |
PRO_MAX_UPLOAD_BYTES |
Request body limit. The default is 100 MiB |
OTEL_EXPORTER_OTLP_ENDPOINT |
Turns on OTLP export of traces, logs and metrics |
XBERG_PRO_CONFIG_FILE |
Path of an optional TOML file, mounted into the container |
For S3 credentials, the AWS credential chain and the Azure and GCS settings, see Pro configuration and AWS storage. The full variable list is in Pro configuration.
Upgrade
Section titled “Upgrade”Pro stops while the packaged role and schema migrations run. The upgrade is a maintenance interval, not a rolling update. Plain docker compose up does not drain a running instance before the migration, so use this sequence:
-
Back up the PostgreSQL volume and the
xberg-datavolume. See Backup and restore. -
Download the chart release for the new version as in step 1, then copy
pro-db-bootstrap.shand the*.sqlfiles over the ones inscripts/andsql/. -
Set
PRO_IMAGEin.env.proto the digest that release names, and pull it:Terminal window docker compose --env-file .env.pro -f docker-compose.pro.yml pull pro -
Stop Pro and wait for it to exit, which drains in-flight jobs:
Terminal window docker compose --env-file .env.pro -f docker-compose.pro.yml stop pro -
Run the bootstrap again, start Pro and enable claims:
Terminal window docker compose --env-file .env.pro -f docker-compose.pro.yml run --rm db-bootstrapdocker compose --env-file .env.pro -f docker-compose.pro.yml up --detach --wait prodocker compose --env-file .env.pro -f docker-compose.pro.yml run --rm --no-deps db-claims-enable
On an existing volume, db-bootstrap rotates the nine role passwords to the values in .env.pro, repairs role membership and rebuilds the grants. Keep all nine passwords stable between routine restarts, because changing one is a credential rotation. A bootstrap failure leaves Pro stopped. Fix the reported error and rerun the same step. Read the release notes for the target version first, and see Upgrades for the policy across versions.
Do not downgrade across a schema-ownership boundary by starting an older image. Contact support for a version-specific rollback plan.