One-Line Install Script

Downloads the compose files, generates a SECRET_KEY, starts all services with docker compose up -d --wait, and starts Watchtower as an external updater for automatic daily updates.

Prerequisites: Docker Desktop must be installed and running.

For Linux/macOS users:

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

For Windows users (PowerShell):

irm https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.ps1 | iex

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

If an NVIDIA GPU and NVIDIA Container Toolkit are detected, the installer asks whether to use GPU acceleration and chooses the compatible backend image automatically. Non-interactive installs default to CPU unless you pass an explicit flag.

Interactive installs also ask whether to enable automatic daily updates with Watchtower, noting that updates may download several GB in the background.

GPU options

Linux/macOS:

# CUDA 12.8
curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash -s -- --variant=cuda

# CUDA 12.6 fallback for older driver stacks
curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash -s -- --variant=cuda126

# Reserve all available GPUs
curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash -s -- --gpu --gpu-count=all

PowerShell:

# Save the script locally first when passing PowerShell parameters.
.\install.ps1 -Variant cuda
.\install.ps1 -Variant cuda126 -GpuCount all

The installer writes the same .env settings you would configure manually: SURFSENSE_VARIANT selects the backend image and COMPOSE_FILE enables the GPU overlay.

To skip Watchtower (e.g. in production where you manage updates yourself, or to avoid large background image downloads):

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.

Manual updates use the same compose state stored in .env, so GPU overlays and variants are preserved:

cd surfsense
docker compose pull
docker compose up -d --wait

If Watchtower is enabled, it preserves the running image variant tag automatically. Because SurfSense images are large, use --no-watchtower when you prefer to manage update timing yourself.

Access SurfSense

After starting, access SurfSense at:

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

The installer uses the bundled Caddy reverse proxy by default. The backend and zero-cache containers are not published on separate host ports in the production stack.

For a custom domain, edit surfsense/.env after installation:

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

Then run:

cd surfsense
docker compose up -d --wait