7297dbd2a8
_client_ip trusted the first X-Forwarded-For hop unconditionally, so anyone able to reach the app port could forge XFF and dodge the login/register/reset/demo rate limits. Now trust XFF ONLY when the request's socket peer is a configured reverse proxy (settings.trusted_proxy_ips, e.g. the VPS Caddy's WireGuard peer IP), and take the RIGHTMOST entry — the client our proxy actually saw and appended, immune to a client pre-seeding a fake XFF. A request from any other peer (hitting the port directly) is keyed on its real socket IP, so XFF can't be forged to bypass the limits. New TRUSTED_PROXY_IPS env (empty default = no proxy, use the direct peer). Documented in .env.example, docs/self-hosting.md, README. Unit-verified against spoof-through-proxy and direct-bypass cases.
133 lines
6.2 KiB
Markdown
133 lines
6.2 KiB
Markdown
# Self-hosting Siftlode
|
|
|
|
Run your own private Siftlode instance with Docker. You don't need the source code — the app runs
|
|
from a prebuilt image, and everything user-facing (your admin account, Google sign-in, email) is
|
|
configured in a web wizard on first start. There's no editing of config files by hand.
|
|
|
|
## What you need
|
|
|
|
- A machine with **Docker** and the **Docker Compose plugin** (Docker Desktop on Windows/macOS,
|
|
or Docker Engine on Linux).
|
|
- A few hundred MB of disk and ~1 GB RAM free for the app itself. The optional Download Center
|
|
stores media too — budget disk for whatever you download (it's bounded by per-user quotas you
|
|
set as admin).
|
|
- Optional: a domain name + reverse proxy if you want HTTPS / public access (see below).
|
|
|
|
## 1. Get the files
|
|
|
|
Download these into a new, empty folder:
|
|
|
|
- `docker-compose.selfhost.yml`
|
|
- `install.sh` (Linux/macOS) **or** `install.ps1` (Windows)
|
|
|
|
The app image is published at `forge.b1fr0st.eu/peter/siftlode` (public — no login to pull).
|
|
|
|
## 2. Run the installer
|
|
|
|
**Linux / macOS:**
|
|
|
|
```bash
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
|
|
```powershell
|
|
./install.ps1
|
|
```
|
|
|
|
The installer asks for the **public URL** where the instance will be reached (just press Enter for
|
|
`http://localhost:8080` to try it locally). It then:
|
|
|
|
- generates the secrets it needs (`SECRET_KEY`, `TOKEN_ENCRYPTION_KEY`, a database password) into a
|
|
local `.env` file — keep that file private,
|
|
- pulls the image and starts the app + database,
|
|
- prints the **setup wizard URL**, which looks like `…/setup?token=…`.
|
|
|
|
## 3. Finish in the web wizard
|
|
|
|
Open the printed setup URL in your browser. The one-time token in it means only you (with access to
|
|
the server logs) can run setup. Then click through:
|
|
|
|
1. **Admin account** — your email + a password. This is how you'll sign in.
|
|
2. **Google sign-in** *(optional)* — paste a Google OAuth client ID + secret to enable "Sign in with
|
|
Google" and pulling your YouTube subscriptions. Skip it to use email + password only.
|
|
3. **Email / SMTP** *(optional)* — an SMTP server so the app can send verification and notification
|
|
emails. Skip it — without email, new registrations are simply approved by you (the admin) instead.
|
|
4. **Finish** — the wizard disappears, the instance is now configured, and you land on the sign-in
|
|
page. Log in with the admin account you just created.
|
|
|
|
That's it. You can change any of the optional settings later under the admin **Configuration** page.
|
|
|
|
> The setup wizard only exists until you finish it. After that, the setup routes are disabled and
|
|
> the token is invalidated — there's no setup surface left on a configured instance.
|
|
|
|
## Getting a Google OAuth client (optional)
|
|
|
|
Only needed for "Sign in with Google" / YouTube access. In the
|
|
[Google Cloud Console](https://console.cloud.google.com/): create a project → **APIs & Services →
|
|
Credentials → Create credentials → OAuth client ID** → *Web application*. Add your instance's
|
|
`…/auth/callback` URL as an **Authorized redirect URI**, then copy the **client ID** and **secret**
|
|
into the wizard's Google step. (Enable the **YouTube Data API v3** for the project too.)
|
|
|
|
## HTTPS / public access
|
|
|
|
The app is served on port `8080` over plain HTTP, which is fine for a LAN or a quick trial. For
|
|
public access, put a reverse proxy (Caddy, Nginx, Traefik…) in front to terminate TLS, and set the
|
|
**public URL** in the installer to your `https://…` address (this also marks the session cookie
|
|
secure). If you've already run the installer, edit `OAUTH_REDIRECT_URL` in `.env` to the https
|
|
callback URL and `docker compose -f docker-compose.selfhost.yml up -d`.
|
|
|
|
**Behind a proxy, set `TRUSTED_PROXY_IPS`.** The login / registration / password-reset rate limiters
|
|
identify callers by IP. Behind a proxy every request arrives from the proxy, so without this the
|
|
limits would apply to everyone together. Set `TRUSTED_PROXY_IPS` in `.env` to the address your proxy
|
|
connects to the app *from* (as the app sees it — e.g. its Docker/host/LAN IP, **not** the public
|
|
client address), and the app will read the real client IP from the proxy's `X-Forwarded-For` header:
|
|
|
|
```bash
|
|
TRUSTED_PROXY_IPS=172.18.0.1 # comma-separate multiple proxies
|
|
```
|
|
|
|
Only that peer is trusted, so a request sent straight to port `8080` (bypassing the proxy) can't forge
|
|
`X-Forwarded-For` to dodge the limits — it's rate-limited by its real address. Leave it empty if the
|
|
app is exposed directly with no proxy. Make sure your proxy actually sets `X-Forwarded-For` (Caddy's
|
|
`reverse_proxy` and Nginx's `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` both do).
|
|
|
|
## Download Center (media storage)
|
|
|
|
The stack includes a **Download Center**: an admin-enabled feature that saves videos to the server
|
|
with yt-dlp (Plex-friendly folders + `.nfo`/poster), lets users trim/crop/join clips, and shares
|
|
them. It runs two extra containers that come up automatically — a `worker` (the download/edit job
|
|
loop) and a small `bgutil-pot` sidecar (mints YouTube tokens so downloads aren't bot-blocked). No
|
|
configuration is required; per-user storage quotas are set on the admin **Downloads → System** page.
|
|
|
|
By default the media lives in a Docker-managed volume (`siftlode_downloads`). To keep it somewhere
|
|
you can reach from other apps — e.g. a folder your **Plex** server indexes — point it at a host
|
|
directory by adding this to `.env` and re-running `up -d`:
|
|
|
|
```bash
|
|
DOWNLOAD_HOST_PATH=/mnt/media/youtube
|
|
```
|
|
|
|
The directory must be writable by the container user (uid `1000`): `sudo chown -R 1000:1000 <dir>`.
|
|
|
|
## Day-to-day
|
|
|
|
```bash
|
|
# Update to the latest release
|
|
docker compose -f docker-compose.selfhost.yml pull
|
|
docker compose -f docker-compose.selfhost.yml up -d
|
|
|
|
# Logs / status (api = web, worker = downloads/edits)
|
|
docker compose -f docker-compose.selfhost.yml logs -f api
|
|
docker compose -f docker-compose.selfhost.yml logs -f worker
|
|
docker compose -f docker-compose.selfhost.yml ps
|
|
|
|
# Stop
|
|
docker compose -f docker-compose.selfhost.yml down
|
|
```
|
|
|
|
Your data (accounts, subscriptions, playlists, the video catalog) lives in the `siftlode_pgdata`
|
|
Docker volume — back that up to keep your instance's state. Database migrations run automatically
|
|
when the app starts, so updating is just pull + up.
|