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.

Backups

The state worth backing up lives in Docker volumes: postgres_data (application data), weaviate_data (search index — recreatable by re-running pipelines), and ollama_data (downloaded models — re-downloadable). For a simple backup, stop the stack and archive those volumes with your usual Docker volume backup tooling.

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 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.

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.