Docker Installation

This guide explains how to run SurfSense using Docker, with options ranging from a single-command install to a fully manual setup.

Quick Start

Option 1 — Install Script (recommended)

Downloads the compose files, generates a SECRET_KEY, starts all services, and sets up Watchtower for automatic daily updates.

curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash

This creates a ./surfsense/ directory with docker-compose.yml and .env, then runs docker compose up -d.

To skip Watchtower (e.g. in production where you manage updates yourself):

curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash -s -- --no-watchtower

To customise the check interval (default 24h), use --watchtower-interval=SECONDS.

Option 2 — Manual Docker Compose

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:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Electric SQL: http://localhost:5133

Updating

Option 1 — Watchtower daemon (recommended, auto-updates every 24 h):

If you used the install script (Option 1 above), Watchtower is already running. No extra setup needed.

For manual Docker Compose installs (Option 2), start 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

Option 2 — Watchtower one-time update:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --run-once \
  --label-filter "com.docker.compose.project=surfsense"

Option 3 — Manual:

cd surfsense   # or SurfSense/docker if you cloned manually
docker compose pull && docker compose up -d

Database migrations are applied automatically on every startup.

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

Ports

Custom Domain / Reverse Proxy

Only set these if serving SurfSense on a real domain via a reverse proxy (Caddy, Nginx, Cloudflare Tunnel, etc.). Leave commented out for standard localhost deployments.

Database

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

Electric SQL

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 pattern http://localhost:8000/api/v1/auth/<connector>/connector/callback.

For Airtable, create an OAuth integration at the Airtable Developer Hub.

Observability (optional)

Advanced (optional)

Docker Services

All services start automatically with docker compose up -d.

The backend includes a health check — dependent services (workers, frontend) wait until the API is fully ready before starting. You can monitor startup progress with docker compose ps (look for (health: starting) → (healthy)).

Development Compose File

If you're contributing to SurfSense and want to build from source, use docker-compose.dev.yml instead:

cd SurfSense/docker
docker compose -f docker-compose.dev.yml up --build

This file builds the backend and frontend from your local source code (instead of pulling prebuilt images) and includes pgAdmin for database inspection at http://localhost:5050. Use the production docker-compose.yml for all other cases.

The following .env variables are only used by the dev compose file (they have no effect on the production docker-compose.yml):

In the production compose file, the NEXT_PUBLIC_* frontend variables are automatically derived from AUTH_TYPE, ETL_SERVICE, and the port settings. In the dev compose file, they are passed as build args since the frontend is built from source.

Migrating from the All-in-One Container

Useful Commands

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

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

# 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

• Ports already in use — Change the relevant *_PORT variable in .env and restart.
• Permission errors on Linux — You may need to prefix docker commands with sudo.
• Electric SQL not connecting — Check docker compose logs electric. If it shows domain does not exist: db, ensure ELECTRIC_DATABASE_URL is not set to a stale value in .env.
• Real-time updates not working in browser — Open DevTools → Console and look for [Electric] errors. Check that NEXT_PUBLIC_ELECTRIC_URL matches the running Electric SQL address.
• Line ending issues on Windows — Run git config --global core.autocrlf true before cloning.