diff --git a/config/settings/prod.py b/config/settings/prod.py index 3d5fda9..00a1b47 100644 --- a/config/settings/prod.py +++ b/config/settings/prod.py @@ -3,12 +3,30 @@ from .base import env DEBUG = False -# nginx terminates TLS and proxies to gunicorn over a Unix socket (see -# docs/install.md) — this tells Django's request.is_secure() to trust the -# header nginx sets, and the redirect/cookie/HSTS settings below assume it. +# A reverse proxy (nginx, Caddy, Traefik, Nginx Proxy Manager on another +# host, ...) is required in front of gunicorn in every deployment — see +# docs/install.md — and it's always the one terminating TLS. This tells +# Django's request.is_secure() to trust the X-Forwarded-Proto header it +# sets, and the redirect/cookie/HSTS settings below assume it's set. SECURE_SSL_REDIRECT = env.bool("SECURE_SSL_REDIRECT", default=True) SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https") +# WhiteNoise serves /static/ directly from gunicorn instead of relying on +# the reverse proxy to alias the staticfiles directory on disk — the proxy +# may not even be on this host (see docs/install.md), so it can't be +# trusted to have filesystem access to $APP_DIR/staticfiles. +MIDDLEWARE = [ + "django.middleware.security.SecurityMiddleware", + "whitenoise.middleware.WhiteNoiseMiddleware", + *MIDDLEWARE[1:], # noqa: F405 +] +STORAGES = { + "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"}, + "staticfiles": { + "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage", + }, +} + SESSION_COOKIE_SECURE = True CSRF_COOKIE_SECURE = True SESSION_COOKIE_SAMESITE = "Lax" diff --git a/docs/deploy/evection-gunicorn.service b/docs/deploy/evection-gunicorn.service index 117e673..9d5f1fb 100644 --- a/docs/deploy/evection-gunicorn.service +++ b/docs/deploy/evection-gunicorn.service @@ -9,11 +9,12 @@ Group=evection WorkingDirectory=/opt/evection/app EnvironmentFile=/opt/evection/app/.env Environment=DJANGO_SETTINGS_MODULE=config.settings.prod -RuntimeDirectory=evection -ExecStart=/opt/evection/venv/bin/gunicorn \ - --workers 3 \ - --bind unix:/run/evection/gunicorn.sock \ - config.wsgi:application +# Evection is always meant to sit behind a reverse proxy (see +# docs/install.md) — it listens on a plain TCP address, never a Unix +# socket, so that proxy can be on this host or a different one. +# EVECTION_GUNICORN_BIND (set in .env by scripts/install.sh) controls +# what address:port that is. +ExecStart=/bin/sh -c 'exec /opt/evection/venv/bin/gunicorn --workers 3 --bind "$EVECTION_GUNICORN_BIND" config.wsgi:application' ExecReload=/bin/kill -s HUP $MAINPID Restart=on-failure diff --git a/docs/deploy/nginx.conf.example b/docs/deploy/nginx.conf.example index cc4dd07..62c2c5b 100644 --- a/docs/deploy/nginx.conf.example +++ b/docs/deploy/nginx.conf.example @@ -1,6 +1,12 @@ -# Reverse proxy for Evection. Copy to /etc/nginx/sites-available/evection, -# adjust server_name and the certificate paths (certbot will fill those in -# for you if you use `certbot --nginx`), then symlink into sites-enabled. +# Reverse proxy for Evection, for the case where nginx runs on the SAME host +# as Evection (see docs/install.md's "Reverse proxy" section — if your proxy +# is on a different host/VM instead, e.g. Nginx Proxy Manager, this file +# doesn't apply to you directly, but the proxy_set_header lines below still +# show what any proxy needs to forward). Copy to +# /etc/nginx/sites-available/evection, adjust server_name, the certificate +# paths (certbot will fill those in for you if you use `certbot --nginx`), +# and the port in proxy_pass if you didn't use EVECTION_GUNICORN_BIND's +# default of 127.0.0.1:8000, then symlink into sites-enabled. server { listen 80; @@ -24,6 +30,11 @@ server { client_max_body_size 10M; # OPML uploads are small, but leave headroom + # Optional: gunicorn already serves /static/ itself via WhiteNoise (with + # its own far-future cache headers, since filenames are content-hashed), + # so this block is purely a same-host perf optimization that skips + # gunicorn for static assets — not required, and not an option at all + # once the proxy is on a different host than $APP_DIR/staticfiles. location /static/ { alias /opt/evection/app/staticfiles/; expires 30d; @@ -36,7 +47,7 @@ server { # else below, so no special-casing is needed here. location / { - proxy_pass http://unix:/run/evection/gunicorn.sock; + proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; diff --git a/docs/install.md b/docs/install.md index 1e37e1a..57ab7b2 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,9 +1,16 @@ # Installing Evection Evection is a traditional Python/Django application: `pip install`, a WSGI server -(gunicorn), a Celery worker + beat scheduler for background feed polling, and an -nginx reverse proxy in front of it. There's no Docker image for v1 — everything -below runs directly on the host. +(gunicorn), and a Celery worker + beat scheduler for background feed polling. +There's no Docker image for v1 — everything below runs directly on the host. + +**A reverse proxy in front of gunicorn is required, always** — Evection has no +TLS support of its own and assumes one is terminating HTTPS for it (see "Reverse +proxy" below). It can be nginx/Caddy/Traefik running on the same host, or +something like Nginx Proxy Manager running on an entirely different host/VM — +`scripts/install.sh` doesn't set one up for you, since which one and where it +runs is up to you; it just leaves gunicorn listening on a TCP address for that +proxy to reach. Both SQLite and PostgreSQL are fully supported. Steps that differ are marked **SQLite** / **Postgres**; everything else applies to both. @@ -32,9 +39,11 @@ run at all until a tag exists. ## Quick install Once the prerequisites below are in place, `scripts/install.sh` automates -everything from "create a system user" through "systemd units are running" — -and optionally nginx + a Let's Encrypt certificate too. It's interactive -(asks for your domain and database choice) and safe to re-run. +everything from "create a system user" through "systemd units are running", +including asking where your reverse proxy will run so it can set up gunicorn's +listen address accordingly. It's interactive (asks for your domain, database +choice, and proxy location) and safe to re-run. It does **not** set up the +proxy itself — see "Reverse proxy" below for that, once this finishes. ```bash sudo mkdir -p /opt/evection @@ -61,14 +70,16 @@ and 4 below first — prerequisites and what `.env` controls. - **Postgres only**: a PostgreSQL server (12+) and its client headers if you're not using the bundled `psycopg[binary]` wheel (most platforms are covered by the wheel, so this is rarely needed) -- nginx (or another reverse proxy) -- A domain name pointed at the host, if you want this reachable outside your LAN +- A reverse proxy, already running or that you're about to set up — on this + host or a different one (see "Reverse proxy" below) +- A domain name pointed at wherever that proxy terminates TLS, if you want + this reachable outside your LAN Debian/Ubuntu example for the non-Python pieces (swap `python3.13-venv` for whatever `python3 --version` reports on your system): ```bash -sudo apt install redis-server nginx python3.13-venv +sudo apt install redis-server python3.13-venv # Postgres only: sudo apt install postgresql ``` @@ -129,11 +140,15 @@ At minimum, set the following in `.env`: sudo -u postgres createdb evection -O evection ``` - `REDIS_URL` — `redis://localhost:6379/0` is fine for a single-host install +- `EVECTION_GUNICORN_BIND` — the `address:port` gunicorn listens on; see + "Reverse proxy" below for how to pick this Evection reads `config.settings.prod` when run via the commands below (see each systemd unit's `DJANGO_SETTINGS_MODULE`). That module turns on HTTPS-only cookies, -HSTS, and a Content-Security-Policy header on top of the base settings — see -`config/settings/prod.py` if you need to adjust it for your proxy setup. +HSTS, and a Content-Security-Policy header on top of the base settings, and +serves static files itself via WhiteNoise rather than relying on the proxy to +have filesystem access to this host — see `config/settings/prod.py` if you need +to adjust any of that. ## 5. Initialize the database and static files @@ -192,28 +207,47 @@ sudo systemctl status evection-gunicorn evection-celery-worker evection-celery-b sudo journalctl -u evection-gunicorn -f ``` -## 7. nginx +## 7. Reverse proxy -Copy `docs/deploy/nginx.conf.example` to `/etc/nginx/sites-available/evection`, -adjust `server_name` and the certificate paths, then enable it: +gunicorn only ever listens on plain HTTP, on the `EVECTION_GUNICORN_BIND` +address you set in step 4 — it never terminates TLS itself. A reverse proxy +in front of it is not optional: it's what the setup wizard, login, and every +other page actually get reached through. Two shapes this takes: + +**Proxy on the same host as Evection.** Set `EVECTION_GUNICORN_BIND=127.0.0.1:8000` +(install.sh's default when you say the proxy is local) so gunicorn isn't +reachable from outside this machine at all — only the proxy, listening on +80/443, is. `docs/deploy/nginx.conf.example` is a working nginx config for +this case; copy it into place and get a certificate the usual way: ```bash sudo cp docs/deploy/nginx.conf.example /etc/nginx/sites-available/evection +# edit it: server_name, and the proxy_pass port if you didn't use 8000 sudo ln -s /etc/nginx/sites-available/evection /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx -``` - -Get a TLS certificate (Let's Encrypt via certbot is the easiest path): - -```bash sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.example ``` -Evection's `prod` settings enable `SECURE_SSL_REDIRECT` and HSTS by default, so -plan to have TLS working before your first real visit — see -`config/settings/prod.py` to disable the redirect temporarily if you need to debug -over plain HTTP first. +**Proxy on a different host or VM** (Nginx Proxy Manager, a Caddy box, a +container host, etc.). Set `EVECTION_GUNICORN_BIND=0.0.0.0:8000` (or to this +host's specific IP) so the proxy can actually reach gunicorn over the +network, then **firewall that port to only accept connections from the +proxy's host** — gunicorn itself has no auth in front of it, so it must +never be reachable from the open internet directly. Point the proxy's +upstream/forward target at `this-host:8000`, and make sure it forwards +`X-Forwarded-Proto` (whatever sets up TLS passthrough/termination normally +handles this, but double-check — see the next paragraph for why it matters). +Whichever proxy you use, `docs/deploy/nginx.conf.example`'s `location /` +block shows the three headers that need forwarding either way. + +Either way, the proxy must set `X-Forwarded-Proto: https` on requests it +forwards once it's terminating TLS — Evection's `prod` settings +(`SECURE_PROXY_SSL_HEADER` in `config/settings/prod.py`) trust that header to +know the original request was HTTPS, which is what keeps `SECURE_SSL_REDIRECT` +from causing a redirect loop. Plan to have TLS working end-to-end before your +first real visit; see `config/settings/prod.py` to disable the redirect +temporarily if you need to debug over plain HTTP first. ## 8. Visit the site @@ -257,9 +291,10 @@ Equivalent by hand: ```bash cd /opt/evection/app -sudo -u evection -H git fetch --tags --force -LATEST_TAG="$(sudo -u evection -H git tag --sort=-creatordate | head -n1)" -sudo -u evection -H git checkout --detach "$LATEST_TAG" +git fetch --tags --force +LATEST_TAG="$(git tag --sort=-creatordate | head -n1)" +git checkout --detach "$LATEST_TAG" +chown -R evection:evection /opt/evection/app sudo -u evection -H /opt/evection/venv/bin/pip install . sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \ /opt/evection/venv/bin/python manage.py migrate diff --git a/pyproject.toml b/pyproject.toml index eeaae2a..ce32b81 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,7 @@ dependencies = [ "psycopg[binary]>=3.1,<4", "gunicorn>=21,<24", "django-csp>=4.0,<5", + "whitenoise>=6.6,<7", ] [project.optional-dependencies] diff --git a/scripts/install.sh b/scripts/install.sh index 39d2240..2d40ab3 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -1,6 +1,11 @@ #!/usr/bin/env bash # Automates docs/install.md's manual steps: system user, virtualenv, .env, -# migrate/collectstatic, systemd units, and (optionally) nginx + TLS. +# migrate/collectstatic, systemd units. Does NOT set up a reverse proxy — +# Evection always requires one in front of gunicorn (see docs/install.md), +# but which one (local nginx/Caddy/Traefik, or something like Nginx Proxy +# Manager on a different host entirely) is up to you, so this script just +# leaves gunicorn listening on EVECTION_GUNICORN_BIND for you to point it +# at. # # Run as root, from inside the checkout you want to serve: # sudo ./scripts/install.sh @@ -11,7 +16,7 @@ # Non-interactive use (e.g. scripted provisioning) — set these before # running, and the script won't prompt: # EVECTION_ALLOWED_HOSTS, EVECTION_DATABASE_URL, EVECTION_REDIS_URL, -# EVECTION_USER (defaults to "evection") +# EVECTION_GUNICORN_BIND, EVECTION_USER (defaults to "evection") set -euo pipefail @@ -58,12 +63,10 @@ if ! "$PYTHON_BIN" -c 'import ensurepip' >/dev/null 2>&1; then exit 1 fi -for bin in redis-cli nginx; do - if ! command -v "$bin" >/dev/null 2>&1; then - echo "Warning: '$bin' not found on PATH. Install it before going live" \ - "(see docs/install.md's prerequisites section: apt install redis-server nginx)." >&2 - fi -done +if ! command -v redis-cli >/dev/null 2>&1; then + echo "Warning: 'redis-cli' not found on PATH. Install it before going live" \ + "(see docs/install.md's prerequisites section: apt install redis-server)." >&2 +fi # --- 2. System user ----------------------------------------------------- @@ -138,12 +141,31 @@ if [ ! -f "$ENV_FILE" ]; then fi DATABASE_URL="${DATABASE_URL:-sqlite:///$APP_DIR/db.sqlite3}" + GUNICORN_BIND="${EVECTION_GUNICORN_BIND:-}" + if [ -z "$GUNICORN_BIND" ] && [ -t 0 ]; then + echo + echo "Evection must run behind a reverse proxy — gunicorn needs an" \ + "address:port that proxy can reach." + read -rp "Is the reverse proxy on this same machine, or a different one? [same/different] [same]: " PROXY_LOCATION + if [[ "${PROXY_LOCATION:-}" =~ ^[Dd] ]]; then + read -rp "Address:port for gunicorn to listen on (e.g. 0.0.0.0:8000, or this host's own IP:8000) [0.0.0.0:8000]: " GUNICORN_BIND + GUNICORN_BIND="${GUNICORN_BIND:-0.0.0.0:8000}" + echo " Remember to firewall this port to only accept connections" \ + "from the reverse proxy's host." + else + read -rp "Address:port for gunicorn to listen on [127.0.0.1:8000]: " GUNICORN_BIND + GUNICORN_BIND="${GUNICORN_BIND:-127.0.0.1:8000}" + fi + fi + GUNICORN_BIND="${GUNICORN_BIND:-127.0.0.1:8000}" + cat > "$ENV_FILE" < $ENV_FILE already exists — leaving it alone" fi +# Needed below for the final "gunicorn is listening on..." message even +# when $ENV_FILE already existed and the block above was skipped. +GUNICORN_BIND="$(grep -m1 '^EVECTION_GUNICORN_BIND=' "$ENV_FILE" | cut -d= -f2-)" +GUNICORN_BIND="${GUNICORN_BIND:-127.0.0.1:8000}" + # --- 5. Migrate + static files -------------------------------------------- echo "==> Running migrations" @@ -181,49 +208,9 @@ echo "==> Services installed. Checking status..." systemctl --no-pager status evection-gunicorn evection-celery-worker evection-celery-beat \ || echo "One or more services didn't start cleanly — see 'journalctl -u evection-gunicorn' etc." >&2 -# --- 7. nginx (optional) --------------------------------------------------- - -SET_UP_NGINX="${EVECTION_SETUP_NGINX:-}" -if [ -z "$SET_UP_NGINX" ] && [ -t 0 ]; then - echo - read -rp "Set up nginx and an HTTPS certificate now? [y/N]: " SET_UP_NGINX -fi - -if [[ "${SET_UP_NGINX:-}" =~ ^[Yy]$ ]]; then - if ! command -v nginx >/dev/null 2>&1; then - echo "nginx isn't installed — install it first (apt install nginx), then" \ - "run docs/install.md's nginx section manually." >&2 - else - DOMAIN="${EVECTION_DOMAIN:-}" - if [ -z "$DOMAIN" ] && [ -t 0 ]; then - read -rp "Domain name for nginx/TLS (must match a hostname in ALLOWED_HOSTS): " DOMAIN - fi - if [ -z "$DOMAIN" ]; then - echo "No domain given — skipping nginx setup. Run docs/install.md's nginx section manually." >&2 - else - sed -e "s/your-domain.example/$DOMAIN/g" \ - -e "s#/opt/evection#$EVECTION_HOME#g" \ - "$APP_DIR/docs/deploy/nginx.conf.example" > "/etc/nginx/sites-available/evection" - ln -sf /etc/nginx/sites-available/evection /etc/nginx/sites-enabled/evection - if nginx -t; then - systemctl reload nginx - echo "==> nginx configured for $DOMAIN (HTTP only so far)" - if command -v certbot >/dev/null 2>&1; then - certbot --nginx -d "$DOMAIN" || echo "certbot failed — run it manually: certbot --nginx -d $DOMAIN" >&2 - else - echo "certbot isn't installed. Install it and run:" \ - "apt install certbot python3-certbot-nginx && certbot --nginx -d $DOMAIN" >&2 - fi - else - echo "nginx config test failed — not enabling it. Check /etc/nginx/sites-available/evection." >&2 - fi - fi - fi -else - echo "==> Skipping nginx — see docs/install.md step 7 to set it up yourself." -fi - echo echo "==> Done." -echo " Visit the site (once nginx/TLS is in place) — the setup wizard creates your admin account." +echo " gunicorn is listening on $GUNICORN_BIND — point your reverse proxy at it" +echo " (see docs/install.md's \"Reverse proxy\" section) before visiting the site." +echo " Once that's in place, the setup wizard creates your admin account on first visit." echo " To upgrade later: sudo ./scripts/upgrade.sh" diff --git a/scripts/upgrade.sh b/scripts/upgrade.sh index 020e7a9..99469fc 100755 --- a/scripts/upgrade.sh +++ b/scripts/upgrade.sh @@ -26,7 +26,6 @@ APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" EVECTION_HOME="$(dirname "$APP_DIR")" VENV_DIR="$EVECTION_HOME/venv" EVECTION_USER="${EVECTION_USER:-evection}" -SOCKET="/run/evection/gunicorn.sock" # $APP_DIR is owned by $EVECTION_USER, but the git steps below run as # root — without this, git refuses to touch a repo it doesn't own @@ -99,7 +98,21 @@ fi echo "==> Verifying" sleep 2 -if curl -sf --unix-socket "$SOCKET" http://localhost/health/ >/dev/null; then +# gunicorn always listens on a plain TCP address (EVECTION_GUNICORN_BIND in +# .env, set by scripts/install.sh) rather than a Unix socket, since the +# reverse proxy in front of it may be on a different host entirely — see +# docs/install.md. 0.0.0.0 isn't a valid address to connect *to*, so check +# against localhost in that case; this health check only needs to prove +# gunicorn itself is answering on this host, not reach it the way the +# proxy does. +HEALTH_BIND="$(grep -m1 '^EVECTION_GUNICORN_BIND=' "$APP_DIR/.env" | cut -d= -f2-)" +HEALTH_BIND="${HEALTH_BIND:-127.0.0.1:8000}" +HEALTH_HOST="${HEALTH_BIND%:*}" +HEALTH_PORT="${HEALTH_BIND##*:}" +if [ "$HEALTH_HOST" = "0.0.0.0" ]; then + HEALTH_HOST="127.0.0.1" +fi +if curl -sf "http://$HEALTH_HOST:$HEALTH_PORT/health/" >/dev/null; then echo "Health check OK" else echo "Health check FAILED — check: journalctl -u evection-gunicorn -n 50" >&2