Operations & troubleshooting

Everyday commands

docker compose ps                  # status of all services
docker compose logs -f backend     # follow backend logs
docker compose logs -f celery-worker   # follow ingestion job logs
docker compose restart backend     # restart one service
docker compose down                # stop everything (data volumes kept)
docker compose down -v             # stop AND delete all data — irreversible

If you started with a project name (-p name) or custom ports, use the same flags for every command.

Updating to a new version

git pull
docker compose down
docker compose up -d --build

--build rebuilds the backend image with the new code. Data volumes (database, vector index, downloaded models) survive updates; only down -v deletes them.

Caution

There is no database migration tool: the schema SQL only runs against an empty database volume. An update that changes the schema needs docker compose down -v && docker compose up -d --build — which deletes your data. Check the release’s notes before updating a database you care about, and back up first.

Backups

Two things are worth backing up:

• The Docker volumes: postgres_data (application data), weaviate_data (search index — recreatable by re-running pipelines), and ollama_data (downloaded models — re-downloadable). Stop the stack and archive them with your usual Docker volume backup tooling.
• The encryption key at app/.encrypted.bin (a plain file in the checkout, created on first boot). Without it, every stored data-source credential and Google grant in the database is unreadable — a database backup restored without its matching key file is only half a backup.

Running the test suite

The repo ships an API test suite that runs against a dedicated project so it can’t touch your data:

docker compose -p tests down -v          # clean slate
docker compose -p tests up -d
docker compose -p tests --profile test run --rm tests

Common problems

The backend exits or restarts on first boot. Usually a race while PostgreSQL or the network initializes; the container’s restart policy recovers it. If it stays down, read docker compose logs backend — and if the container reports no network attached, recreate it: docker compose up -d --force-recreate backend.

“Port is already allocated” when starting. Another process (or another compose project) holds the port. Pick different values: BACKEND_PORT=8025 SAMBA_PORT=1447 docker compose up -d.

The dashboard shows a blank page mentioning VITE_CLERK_PUBLISHABLE_KEY. The frontend has no Clerk key. Set it in frontend/.env.local (see installation) and restart or rebuild the frontend.

The dashboard loads but every request fails / you’re bounced to sign-in. Almost always CORS or a wrong VITE_BACKEND_URL. The browser’s dev-tools network tab will show blocked requests; fix the origin list as described in configuration.

“Encryption is misconfigured. Contact an administrator.” The backend can’t find its encryption key — usually because the init-kek service never ran (a fresh checkout started with --no-deps, or the key file was deleted). Run docker compose up -d without --no-deps so init-kek can create app/.encrypted.bin.

“Stored credentials could not be read.” The key in app/.encrypted.bin doesn’t match what encrypted the stored credentials (the file was regenerated or restored from the wrong backup). If the original key is gone, delete and recreate the affected data sources.

Model pulls are slow or chat responses take forever. CPU-only inference is slow for anything but small models. Verify GPU passthrough (docker exec -it <ollama container> nvidia-smi) or switch to a smaller model.

Ingestion jobs sit in “pending”. Jobs run one at a time through the Celery worker — check it’s alive with docker compose ps and its logs for errors.

Signing in is extremely slow under load. Password hashing competes for CPU with everything else (embedding, model downloads, inference). It resolves once heavy jobs finish; on busy servers, give the stack more cores.