aa3aae695d
Tier 1 of "secure behind a reverse proxy". STRICTLY opt-in so direct/LAN installs are byte-for-byte unchanged. - core/security/reverse_proxy.py: apply_reverse_proxy_mode(app, config_get) — a no-op unless security.trust_reverse_proxy=true. When OFF (default), the app is untouched: no ProxyFix, X-Forwarded-* stays UNtrusted (a direct client can't spoof its IP/scheme), session cookie keeps Flask defaults. When ON (operator is behind nginx/Caddy/Traefik with TLS): trust one proxy hop's X-Forwarded-*, and mark the session cookie Secure + SameSite=Lax. Any config error → safe no-op, never breaks startup. - Wired once at app init. - Support/REVERSE-PROXY.md: nginx (with the Socket.IO Upgrade headers people always miss) / Caddy / Traefik configs, the setting, and the "put auth in front (Authelia/Authentik/oauth2-proxy)" recommendation + the off-for-plain-HTTP note. Tests: off (and missing-key, and a config exception) is a strict no-op — not ProxyFix-wrapped, cookie defaults intact; on wraps ProxyFix + secures the cookie; and the real web_server app is NOT in proxy mode by default. 5 tests pass.
122 lines
4 KiB
Markdown
122 lines
4 KiB
Markdown
# Running SoulSync behind a reverse proxy (nginx / Caddy / Traefik)
|
|
|
|
Putting SoulSync behind a reverse proxy lets you serve it over **HTTPS** and — the
|
|
important part — put **authentication** in front of it before exposing it to the
|
|
internet. This guide covers the safe setup.
|
|
|
|
> **The golden rule:** the safest way to expose *any* self-hosted app publicly is
|
|
> to require authentication at the proxy (an auth layer), **not** to rely on the
|
|
> app's own protection. SoulSync's launch PIN is a useful fallback, but it is not
|
|
> a substitute for a real auth layer on a public instance.
|
|
|
|
---
|
|
|
|
## 1. Turn on reverse-proxy mode
|
|
|
|
By default SoulSync does **not** trust proxy headers (so a direct client can't spoof
|
|
its IP or pretend the connection is HTTPS). If you're behind a proxy that
|
|
terminates TLS, opt in by setting this in your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"security": {
|
|
"trust_reverse_proxy": true
|
|
}
|
|
}
|
|
```
|
|
|
|
When enabled, SoulSync trusts `X-Forwarded-For/Proto/Host/Port` from **one** proxy
|
|
hop and marks its session cookie `Secure` (HTTPS-only) + `SameSite=Lax`. **Leave
|
|
it off if you access SoulSync directly over http:// on your LAN** — turning it on
|
|
would make the session cookie HTTPS-only and break plain-HTTP access.
|
|
|
|
Restart SoulSync after changing it.
|
|
|
|
---
|
|
|
|
## 2. nginx
|
|
|
|
SoulSync uses WebSockets (Socket.IO), so the `Upgrade`/`Connection` headers are
|
|
**required** — without them live updates silently stop working.
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name soulsync.example.com;
|
|
|
|
ssl_certificate /etc/letsencrypt/live/soulsync.example.com/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/soulsync.example.com/privkey.pem;
|
|
|
|
# Large library scans / uploads
|
|
client_max_body_size 0;
|
|
|
|
location / {
|
|
proxy_pass http://127.0.0.1:8008;
|
|
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header X-Forwarded-Host $host;
|
|
|
|
# Required for Socket.IO / live updates
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
|
|
proxy_read_timeout 3600s; # long-running scans
|
|
proxy_send_timeout 3600s;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Caddy
|
|
|
|
Caddy handles TLS automatically and proxies WebSockets out of the box:
|
|
|
|
```caddy
|
|
soulsync.example.com {
|
|
reverse_proxy 127.0.0.1:8008
|
|
}
|
|
```
|
|
|
|
Caddy sets `X-Forwarded-*` for you. (Add an auth provider directive if you want
|
|
auth at the proxy — see below.)
|
|
|
|
---
|
|
|
|
## 4. Traefik
|
|
|
|
Traefik proxies WebSockets automatically and forwards the headers. Point a router
|
|
at the SoulSync service on port `8008` with your TLS resolver; no extra WebSocket
|
|
config is needed.
|
|
|
|
---
|
|
|
|
## 5. Add authentication in front (recommended for public instances)
|
|
|
|
Pick one:
|
|
|
|
- **Auth proxy** — [Authelia](https://www.authelia.com/),
|
|
[Authentik](https://goauthentik.io/), or
|
|
[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/). These sit in front
|
|
of SoulSync and force a login (with 2FA) before any request reaches it. Best
|
|
option for internet exposure.
|
|
- **HTTP Basic Auth** — quick and simple (nginx `auth_basic` / Caddy `basicauth`).
|
|
Better than nothing; weaker than an auth proxy.
|
|
- **SoulSync launch PIN** — set an admin PIN in Settings. Enforced server-side, so
|
|
it can't be bypassed by hitting the API directly — but it's a shared PIN, so
|
|
treat it as a fallback, not your only gate.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Live updates / progress bars don't move** → the WebSocket `Upgrade`/`Connection`
|
|
headers are missing (nginx) or your proxy is buffering. Check section 2.
|
|
- **Login won't stick / "session expired"** → you enabled `trust_reverse_proxy` but
|
|
are reaching SoulSync over plain `http://`. The session cookie is now HTTPS-only;
|
|
use `https://`, or turn the setting off for direct HTTP access.
|
|
- **Scans time out** → raise `proxy_read_timeout` / `proxy_send_timeout`.
|