Updating

Manual Update

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

Database migrations are applied automatically on every startup. GPU overlays and image variants set in .env are preserved.

Automatic Updates with Watchtower

Auto-updates every 24 hours. If you used the install script and enabled updates, Watchtower is already running — no extra setup needed.

For manual Docker Compose installs, 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

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

For a one-time update instead of a daemon:

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

Migrating from the All-in-One Container

If you previously ran the legacy all-in-one image (ghcr.io/modsetter/surfsense:latest via docker-compose.quickstart.yml), your data lives in a single surfsense-data volume and PostgreSQL has since been upgraded from version 14 to 17 — so a simple volume swap won't work. A one-time dump and restore is required, and the install script does it for you.

Just run the normal install command:

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

It detects the legacy surfsense-data volume, stops the old container, dumps your database with a temporary PostgreSQL 14 container, recovers your SECRET_KEY, restores everything into PostgreSQL 17, and starts the new stack. Your original volume is never deleted — the dump is also saved to ./surfsense_migration_backup.sql as a checkpoint, so if anything fails mid-way you can simply re-run the script.

After it completes:

1. Open SurfSense and confirm your data is intact.
2. Remove the old volume (irreversible): docker volume rm surfsense-data
3. Delete the dump file once you no longer need it: rm ./surfsense_migration_backup.sql

curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/migrate-database.sh -o migrate-database.sh
bash migrate-database.sh --db-user myuser --db-password mypass --db-name mydb
curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash