Skip to main content

Security and publishing

Core principles​

PlexSub stores operational data, users, integration credentials, and sensitive configuration. Treat every installation as sensitive.

Never publish .env, API keys, Plex tokens, SMTP credentials, private Web Push keys, backups, database dumps, cookies, private certificates, or SSH keys.

HTTPS​

When PlexSub is exposed outside your local network, use HTTPS. Set APP_BASE_URL to the public HTTPS URL, FORCE_SECURE_COOKIES=1, and TRUST_PROXY_LEVEL=1 only when a trusted reverse proxy or tunnel is in front of PlexSub. Otherwise use TRUST_PROXY_LEVEL=0.

Reverse proxy​

With Nginx, Caddy, Traefik, Cloudflare Tunnel, or another proxy:

  1. Publish only the required port.
  2. Keep the app listening internally on 5000.
  3. Forward standard proxy headers.
  4. Use HTTPS to the end user.
  5. Review cookies after the first sign-in.

Secrets​

APP_SETTINGS_ENCRYPTION_KEY is critical. Losing it can make encrypted credentials stored in the database inaccessible.

Keep it outside the server where possible, out of Git, unchanged unless you have a rotation plan, and backed up with your restore procedures.

Off-server backups​

A backup that exists only on the same server does not protect against host loss. Copy PostgreSQL, uploads where used, .env, and APP_SETTINGS_ENCRYPTION_KEY securely off-server, then test restoration periodically.

Restore test​

The repository includes docker-compose.restore-test.yml. It uses controlled images through PLEXSUB_RESTORE_POSTGRES_IMAGE and PLEXSUB_RESTORE_APP_IMAGE.

The test should confirm PostgreSQL starts, the app starts, it can read the restored database, and sign-in plus main screens work.

Checklist before publishing​

  • .env is not in Git.
  • APP_BASE_URL points to the final URL.
  • HTTPS and secure cookies are enabled.
  • The proxy is configured and checked.
  • Backups are configured and restoration was tested.
  • External services are diagnosed.
  • No tokens appear in shared documentation, logs, or tickets.