Docker

The SurfSense Docker image, ghcr.io/modsetter/surfsense, runs the desktop app's whole stack in one container: the same app, the same local models, your remote connections and your license. You open it in a browser, from the server itself or from any device on your network.

It is not the old self-hosted stack. That one lives on the legacy branch and is documented under Legacy Docker installation. See Differences for how the two compare.

Docker or the desktop appCopy Anchor Link

RequirementsCopy Anchor Link

• An x86-64 (amd64) machine. ARM machines, including Apple Silicon Macs and Raspberry Pis, are not supported yet. The installer stops on them.
• Docker with the Compose plugin (docker compose). On Windows and macOS, Docker Desktop. On Linux, Docker Engine is enough.
• Several GB of free disk for the image, plus room for the models you download and your documents.

Install with one commandCopy Anchor Link

The installer checks Docker, downloads the compose file and the settings file into a surfsense folder in the current directory, pulls the image and starts it. It asks nothing.

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

The first pull is large, and the first start takes a minute or two. When it is done, the installer prints where to open SurfSense:

  Open:      http://192.168.1.20:4929    (any device on this network)
             http://localhost:4929    (this machine)

  The first visit asks you to create a password.

  Settings:  /home/you/surfsense/.env
  Logs:      cd /home/you/surfsense && docker compose logs -f
  Stop:      cd /home/you/surfsense && docker compose down
  Update:    run this same command again

Running the same command again later updates SurfSense. See Updating.

Install with Docker Compose by handCopy Anchor Link

The installer only automates these steps. To do them yourself:

mkdir surfsense && cd surfsense
curl -fsSLO https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/surfsense/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/surfsense/.env.example
cp .env.example .env
docker compose up -d

Edit .env before docker compose up -d if you want to change anything. Every value is optional. See Configuration.

First sign-inCopy Anchor Link

1. Open http://<server address>:4929 in a browser, or http://localhost:4929 on the server itself.
2. SurfSense shows Set up SurfSense. Enter a password of at least 8 characters and choose Create password.
3. The app opens. Every other device signs in with the same password on Sign in to SurfSense.

Then continue with the Quick start, as on the desktop.

PortsCopy Anchor Link

Both are published on every network the server is on. To keep SurfSense to the server alone, set SURFSENSE_BIND=127.0.0.1. The legacy stack used port 3929, so both can run side by side while you move your data.

Day-to-day commandsCopy Anchor Link

Run these in the install folder, the one holding docker-compose.yml:

docker compose logs -f     # follow the logs
docker compose down        # stop SurfSense; your data stays
docker compose up -d       # start it again, or apply a changed .env

NextCopy Anchor Link

• Configuration: ports, HTTPS, a domain, a reverse proxy.
• Access: the password, sessions, and turning sign-in off.
• Updating: updates, backups and uninstalling.
• Differences: what works differently from the desktop app.