Operations

Commands on this page run from the repository root, with the stack started as described in Docker Compose install.

Backups and restore

Three things hold your data:

• Postgres, in the named volume postgres_data: database records. Temporal also keeps its state in this Postgres instance.
• MinIO, in the named volume minio_data: raw and derived artifacts in the docslurp-files bucket. The LanceDB vector indexes live in the same bucket under the lancedb/ prefix.
• .env.selfhost: the generated credentials and encryption keys. Without the encryption keys, stored credentials and secrets cannot be read.

Redis is an ephemeral rate-limit cache and needs no backup.

Back up all three before upgrading. The commands below write to ./backup.

mkdir -p backup
cp .env.selfhost backup/env.selfhost

# Postgres: the docslurp database, custom format
docker compose --env-file .env.selfhost -f compose.selfhost.yml exec -T postgres \
  pg_dump -U docslurp -d docslurp -Fc > backup/docslurp.dump

# MinIO: the whole bucket, including lancedb/, with the mc client from the createbucket service.
# Runs as your user so it can write to ./backup.
set -a; . ./.env.selfhost; set +a
export MC_HOST_local="http://${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}@minio:9000"
docker compose --env-file .env.selfhost -f compose.selfhost.yml run --rm --no-deps \
  --user "$(id -u):$(id -g)" -e HOME=/tmp -e MC_HOST_local -v "$PWD/backup:/backup" \
  --entrypoint mc createbucket mirror --overwrite local/docslurp-files /backup/minio

The pg_dump covers the docslurp database only. Workflows still in flight in Temporal are not in this dump; resubmit any document that was processing when you took the backup.

selfhost-init generates hex keys, so they are URL-safe in MC_HOST_local. If you chose keys with reserved characters, URL-encode them there.

The image runs as a non-root user that cannot write to a host directory you own, so the command runs as your user. mc reports success even when it cannot write, so check that the copy landed:

find backup/minio -type f | head

To restore, use a stack that has not served traffic yet, ideally on a separate host. Order matters:

1. Put the saved file back as .env.selfhost.

2. Start only the data services: docker compose --env-file .env.selfhost -f compose.selfhost.yml up -d postgres minio. Wait until Postgres accepts connections.

3. Restore Postgres:

   shCopy

   docker compose --env-file .env.selfhost -f compose.selfhost.yml exec -T postgres \
     pg_restore -U docslurp -d docslurp --clean --if-exists < backup/docslurp.dump

4. Restore the bucket. Export MC_HOST_local as in the backup step first.

   shCopy

   docker compose --env-file .env.selfhost -f compose.selfhost.yml run --rm --no-deps \
     --user "$(id -u):$(id -g)" -e HOME=/tmp -e MC_HOST_local \
     --entrypoint mc createbucket mb --ignore-existing local/docslurp-files
   docker compose --env-file .env.selfhost -f compose.selfhost.yml run --rm --no-deps \
     --user "$(id -u):$(id -g)" -e HOME=/tmp -e MC_HOST_local -v "$PWD/backup:/backup" \
     --entrypoint mc createbucket mirror --overwrite /backup/minio local/docslurp-files

5. Start everything: docker compose --env-file .env.selfhost -f compose.selfhost.yml up -d --build.

Test a restore on a separate host before you rely on it.

Upgrades

To upgrade, pull the chosen release and run the same up -d --build command. The one-shot migrate service applies the checked-in migrations before the server and worker start. Watch its exit status and the server logs. Breaking schema changes are possible while DocSlurp is pre-release; read release notes before upgrading and keep a rollback backup (see Backups and restore).

Monitoring

• GET /health returns {"ok":true,...} while the server process is up. The container healthcheck uses it.
• GET /ready checks dependencies and returns 503 when a critical one fails. Only Fly deployments redact it for public requests (arrivedThroughPublicEdge in server/src/routes/health.ts, which needs FLY_APP_NAME). In the Compose stack /ready returns full detail to every caller: latencies, schema version and error text. For a public deployment, block /ready and /metrics at the reverse proxy. See Public access.
• GET /metrics returns Prometheus text. It needs Authorization: Bearer <METRICS_SECRET>, using the METRICS_SECRET value from .env.selfhost. It returns 404 when METRICS_SECRET is unset and 401 when the header is wrong.
• Container logs: docker compose --env-file .env.selfhost -f compose.selfhost.yml logs -f server worker.

Watch disk, memory, worker errors and /health before inviting users.

Scaling workers on one host

Each worker processes WORKER_DOC_CONCURRENCY documents at a time (default 1). To use more of one machine, either raise that value in .env.selfhost or run more worker containers:

docker compose --env-file .env.selfhost -f compose.selfhost.yml up -d --scale worker=2

With the full worker: docker compose --env-file .env.selfhost -f compose.selfhost.yml --profile full up -d --scale worker=0 --scale worker-full=2.

Memory is the limit. Raise one setting at a time and watch memory and latency after each change. See sizing for what has been measured. This is scaling on a single host, not a multi-host design.

Troubleshooting