apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-04-26 09:16:22 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: enhance Docker installation and migration documentation with updated steps and options for managing updates

Browse source
This commit is contained in:
Anish Sarkar 2026-02-26 19:11:57 +05:30
parent 90f18fac38
commit 2e8e85a4ef
2 changed files with 51 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

60
surfsense_web/content/docs/docker-installation.mdx
View file

@ -36,6 +36,41 @@ After starting, access SurfSense at:
---
## Updating
**Option 1 — Watchtower daemon (recommended, auto-updates every 24 h):**
```bash
docker run -d --name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--label-enable \
--interval 86400
```
**Option 2 — Watchtower one-time update:**
```bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower --run-once \
--label-filter "com.docker.compose.project=surfsense"
```
<Callout type="warn">
Use `nickfedor/watchtower`. The original `containrrr/watchtower` is no longer maintained and may fail with newer Docker versions.
</Callout>
**Option 3 — Manual:**
```bash
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.
@ -181,31 +216,6 @@ See the full step-by-step guide: [Migrate from the All-in-One Container](/docs/h
---
## Updating
**Option 1 — Watchtower (recommended):**
```bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower --run-once \
--label-filter "com.docker.compose.project=surfsense"
```
<Callout type="warn">
Use `nickfedor/watchtower`. The original `containrrr/watchtower` is no longer maintained and may fail with newer Docker versions.
</Callout>
**Option 2 — Manual:**
```bash
cd surfsense # or SurfSense/docker if you cloned manually
docker compose pull && docker compose up -d
```
Database migrations are applied automatically on every startup.
---
## Useful Commands
```bash

24
surfsense_web/content/docs/how-to/migrate-from-allinone.mdx
View file

@ -85,7 +85,15 @@ bash migrate-database.sh --db-user myuser --db-password mypass --db-name mydb
For users who prefer full control or whose platform doesn't support bash scripts (e.g. Windows without WSL2).
### Step 1 — Start a temporary PostgreSQL 14 container
### Step 1 — Stop the old all-in-one container
Before mounting the `surfsense-data` volume into a new container, stop the existing one to prevent two PostgreSQL processes from writing to the same data directory:
```bash
docker stop surfsense 2>/dev/null || true
```
### Step 2 — Start a temporary PostgreSQL 14 container
```bash
docker run -d --name surfsense-pg14-temp \
@ -103,20 +111,20 @@ Wait ~10 seconds, then confirm it is healthy:
docker exec surfsense-pg14-temp pg_isready -U surfsense
```
### Step 2 — Dump the database
### Step 3 — Dump the database
```bash
docker exec -e PGPASSWORD=surfsense surfsense-pg14-temp \
pg_dump -U surfsense surfsense > surfsense_backup.sql
```
### Step 3 — Recover your SECRET\_KEY
### Step 4 — Recover your SECRET\_KEY
```bash
docker run --rm -v surfsense-data:/data alpine cat /data/.secret_key
```
### Step 4 — Set up the new stack
### Step 5 — Set up the new stack
```bash
mkdir -p surfsense/scripts
@ -128,9 +136,9 @@ chmod +x surfsense/scripts/init-electric-user.sh
cp surfsense/.env.example surfsense/.env
```
Set `SECRET_KEY` in `surfsense/.env` to the value from Step 3.
Set `SECRET_KEY` in `surfsense/.env` to the value from Step 4.
### Step 5 — Start PostgreSQL 17 and restore
### Step 6 — Start PostgreSQL 17 and restore
```bash
cd surfsense
@ -139,13 +147,13 @@ docker compose exec db pg_isready -U surfsense # wait until ready
docker compose exec -T db psql -U surfsense -d surfsense < ../surfsense_backup.sql
```
### Step 6 — Start all services
### Step 7 — Start all services
```bash
docker compose up -d
```
### Step 7 — Clean up
### Step 8 — Clean up
```bash
docker stop surfsense-pg14-temp && docker rm surfsense-pg14-temp