siftlode/docs/self-hosting.md

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:

chmod +x install.sh
./install.sh

Windows (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: 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:

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:

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

# 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.