Docker Compose

Setup

git clone https://github.com/MODSetter/SurfSense.git
cd SurfSense/docker
cp .env.example .env
# Edit .env, at minimum set SECRET_KEY
docker compose up -d

After starting, access SurfSense at:

• SurfSense: http://localhost:3929
• Backend API: http://localhost:3929/api/v1
• Zero sync: ws://localhost:3929/zero

Configuration

All configuration lives in a single docker/.env file (or surfsense/.env if you used the install script). Copy .env.example to .env and edit the values you need.

Required

Core Settings

Image Variants

SurfSense publishes CPU and CUDA backend image variants. The frontend image is not variant-specific.

All backend variants are published for linux/amd64 and linux/arm64. CUDA on linux/arm64 is best-effort.

NVIDIA GPU Acceleration

For most NVIDIA systems, add these values to .env to use the CUDA 12.8 image:

SURFSENSE_VARIANT=cuda
COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml
SURFSENSE_GPU_COUNT=1

Use SURFSENSE_VARIANT=cuda126 for older NVIDIA driver stacks or older GPUs that need the CUDA 12.6 fallback image.

On Windows, use ; instead of : in COMPOSE_FILE inside .env:

COMPOSE_FILE=docker-compose.yml;docker-compose.gpu.yml

To switch variants later, edit SURFSENSE_VARIANT and COMPOSE_FILE in .env, then run:

docker compose pull
docker compose up -d --wait

Automatic Updates

Manual Docker Compose installs do not start Watchtower automatically. To enable external automatic updates, run Watchtower separately:

docker run -d --name watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --label-enable \
  --interval 86400

SurfSense containers are labeled for Watchtower, so --label-enable limits updates to the SurfSense services.

Public URL and Ports

SurfSense includes Caddy by default. The frontend, backend, and zero-cache containers are internal-only in the production compose file; the browser reaches them through Caddy path routing.

Custom Domain / Automatic HTTPS

For a real domain, point DNS at the Docker host and set:

SURFSENSE_SITE_ADDRESS=surf.example.com
LISTEN_HTTP_PORT=80
LISTEN_HTTPS_PORT=443
CERT_EMAIL=you@example.com
SURFSENSE_PUBLIC_URL=https://surf.example.com

Caddy will issue and renew Let's Encrypt certificates automatically. Ports 80 and 443 must be reachable from the internet for the default HTTP-01 challenge.

Bring Your Own Proxy

If you already run nginx, Traefik, Cloudflare Tunnel, or another ingress, you can comment out the proxy service and route traffic to the internal services with the same path contract:

Alternative proxies must preserve WebSocket upgrades for /zero, avoid buffering streaming responses, allow long-running requests, and support large uploads. For DNS-01 or wildcard certificates with Caddy, build docker/proxy/Dockerfile and set CERT_ACME_DNS for your DNS provider.

Zero-cache (Real-Time Sync)

Defaults work out of the box. Change ZERO_ADMIN_PASSWORD for security in production.

Database

Defaults work out of the box. Change for security in production.

Authentication

Create credentials at the Google Cloud Console.

External API Keys

Connector OAuth Keys

Uncomment the connectors you want to use. Redirect URIs follow the single-origin pattern ${SURFSENSE_PUBLIC_URL}/api/v1/auth/<connector>/connector/callback. For local Docker defaults, that means http://localhost:3929/api/v1/auth/<connector>/connector/callback.

Messaging Channels

Configure these in the same docker/.env file when you want users to chat with SurfSense from external apps. See Messaging Channels for full setup.

Observability (optional)

Advanced (optional)

Docker Services

All services start automatically with docker compose up -d.

How startup ordering works

Schema migrations run as a dedicated migrations service that exits 0 on success and non-zero on failure. Every other backend-image service gates on it via condition: service_completed_successfully:

db (healthy) ──▶ migrations (alembic upgrade head + verify zero_publication)
                     │
                     ├── exit 0 ─▶ backend ──▶ frontend
                     │            celery_worker
                     │            celery_beat
                     │            zero-cache ──▶ frontend
                     │
                     └── exit ≠ 0 ─▶ compose halts the rest of the stack

This guarantees zero-cache only starts after zero_publication exists in Postgres. Before this design, a silent migration failure would leave zero-cache crash-looping with Unknown or invalid publications. Specified: [zero_publication]. Found: [].

Readiness vs liveness

The backend exposes two endpoints:

• GET /health: lightweight liveness probe (always returns 200 if the process is up).
• GET /ready: readiness probe that confirms zero_publication exists. Returns 503 if not. The compose backend.healthcheck uses /ready so the container only reports healthy once the schema is actually usable by zero-cache.

You can also monitor startup progress with docker compose ps (look for (health: starting) → (healthy)). The install script polls these states automatically and times out after 5 minutes if the stack does not converge.

Useful Commands

# View logs (all services)
docker compose logs -f

# View logs for a specific service
docker compose logs -f backend

# Stop all services
docker compose down

# Restart a specific service
docker compose restart backend

# Stop and remove all containers + volumes (destructive!)
docker compose down -v

Troubleshooting

• Port already in use: Change LISTEN_HTTP_PORT in .env and restart. In domain mode, use ports 80 and 443 so Caddy can complete certificate issuance.
• Permission errors on Linux: You may need to prefix docker commands with sudo.
• Real-time updates not working: Open DevTools → Console and check for WebSocket errors. In production Docker the expected URL is ${SURFSENSE_PUBLIC_URL}/zero.
• Line ending issues on Windows: Run git config --global core.autocrlf true before cloning.

Migration service exited non-zero

The migrations service exits non-zero in two cases:

1. alembic upgrade head failed (timeout or SQL error).
2. alembic succeeded but zero_publication is still missing from pg_publication.

Inspect the logs and the alembic state:

docker compose logs migrations
docker compose exec db psql -U surfsense -d surfsense \
  -c 'SELECT * FROM alembic_version;'
docker compose exec db psql -U surfsense -d surfsense \
  -c 'SELECT pubname FROM pg_publication;'

The default migration timeout is 900 seconds. Slow disks (Windows / WSL2) may need more. Set MIGRATION_TIMEOUT in .env to increase it.

Zero-cache stuck on Unknown or invalid publications

Symptom (in docker compose logs zero-cache):

Error: Unknown or invalid publications. Specified: [zero_publication]. Found: []

This means zero-cache started before zero_publication was created or the publication does not match SurfSense's canonical Zero shape. With the current compose files this should be impossible: the migrations service blocks zero-cache from starting and verifies the publication before exiting successfully. If you see it, your stack predates the fix or you brought up zero-cache manually with docker compose up zero-cache before the migrations service ran.

Recovery:

docker compose down
docker volume rm surfsense-zero-cache   # wipe half-built SQLite replica
docker compose up -d                    # migrations runs first, then zero-cache

Zero-cache crashes with _zero.tableMetadata errors

This indicates a half-initialized SQLite replica left behind by a previous crash. Zero's own event triggers and ZERO_AUTO_RESET handle schema and replication halts automatically. If the local SQLite replica is wedged, run the recovery one-liner above to wipe surfsense-zero-cache; zero-cache will re-sync from Postgres on the next start.

Ensuring wal_level = logical

Logical replication is required by zero-cache. The bundled docker/postgresql.conf sets wal_level = logical automatically. If you swap in your own config or use a managed Postgres, confirm with:

docker compose exec db psql -U surfsense -d surfsense \
  -c "SHOW wal_level;"

Using docker-compose.deps-only.yml

docker-compose.deps-only.yml runs only the dependencies (Postgres, Redis, SearXNG, zero-cache) on Docker while the backend and frontend run on the host. Because there is no backend container in this stack, there is no migrations service either, and you must run alembic on the host before bringing the stack up:

cd surfsense_backend
uv run alembic upgrade head
cd ../docker
docker compose -f docker-compose.deps-only.yml up -d

If you skip the alembic step, zero-cache will crash-loop with Unknown or invalid publications. Specified: [zero_publication].