Files
Evection/docs/install.md
T
ksmithandClaude Sonnet 5 a1ea2e5662 Add login rate limiting (S6)
Django's default LoginView had no throttle — an internet-facing
instance was exposed to unlimited password-guessing/credential-
stuffing attempts. apps.accounts.views.LoginView adds two independent,
Redis-cache-backed throttles (shared across all gunicorn workers,
unlike the per-process default LocMemCache): by client address (catches
one attacker spraying many usernames) and by the submitted username
(catches a distributed attack on one specific account). Either blocks
further attempts for a 5-minute window; both are generous enough not
to lock out a user who's just mistyped their own password a few times.

Client address prefers X-Forwarded-For's first hop, falling back to
REMOTE_ADDR — the same reverse-proxy trust boundary config.settings.prod
already relies on for X-Forwarded-Proto (gunicorn is never meant to be
reachable except through that proxy).

CACHES now points at Redis (already a hard install requirement for
Celery) instead of Django's implicit per-process default, since the
whole point is a shared counter across every gunicorn worker; test
settings override it back to LocMemCache so the suite doesn't need a
real Redis instance.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-31 12:46:49 -06:00

13 KiB

Installing Evection

Evection is a traditional Python/Django application: pip install, a WSGI server (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.

Releases

Evection is deployed from git tags, never from a branch tip — the same pattern as the author's other self-hosted projects. A release tag looks like v2026.10.31 (v<year>.<month>.<day>); scripts/install.sh and scripts/upgrade.sh both always deploy whatever tag is newest by creation time, via a detached-HEAD checkout, regardless of what's checked out or committed on main.

Before your first production install, cut and push a tag from whatever commit you want to ship:

git tag v$(date +%Y.%m.%d)
git push --tags

If you skip this, install.sh will just leave the clone on whatever ref you checked out (there's nothing to pin to yet), and upgrade.sh will refuse to 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", 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.

sudo mkdir -p /opt/evection
sudo git clone <your-fork-or-release-url> /opt/evection/app
cd /opt/evection/app
sudo ./scripts/install.sh

(The script creates the evection system user itself and takes ownership of the checkout, and checks out the latest release tag if one exists — see "Releases" above — so you don't need to create the user or pin a tag yourself first.)

The rest of this document explains what that script does, step by step, if you want to run it manually, customize something, or just understand the deployment before trusting a script with root. Either way, read sections 1 and 4 below first — prerequisites and what .env controls.

1. Prerequisites

  • Python 3.11 or 3.12, with its venv module (Debian/Ubuntu split this into a separate python3.X-venv package — see below)
  • Redis (Celery's broker, and the app's cache — e.g. login rate limiting)
  • 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)
  • 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):

sudo apt install redis-server python3.13-venv
# Postgres only:
sudo apt install postgresql

2. Create a dedicated system user

Evection should run as its own unprivileged user, not root and not your personal account:

sudo adduser --system --group --home /opt/evection evection
sudo -u evection -H git clone https://github.com/<you>/evection.git /opt/evection/app
sudo -u evection -H git -C /opt/evection/app checkout --detach <latest-release-tag>

(Swap the git clone for however you're distributing releases — a tagged checkout or an extracted release tarball both work the same way. See "Releases" above for how tags are named and why this stays on a tag rather than a branch.)

3. Python environment

cd /opt/evection/app
sudo -u evection -H python3 -m venv /opt/evection/venv
sudo -u evection -H /opt/evection/venv/bin/pip install .

4. Configure

Copy the example environment file and edit it:

sudo -u evection -H cp .env.example /opt/evection/app/.env
sudo -u evection -H "$EDITOR" /opt/evection/app/.env

Every manage.py command below needs DJANGO_SETTINGS_MODULE=config.settings.prod in its environment — manage.py itself defaults to the dev settings (DEBUG=True) for local convenience, so production commands must override that explicitly (the env DJANGO_SETTINGS_MODULE=... prefix you'll see in the commands below). The systemd units in step 6 set the same thing for gunicorn and Celery.

At minimum, set the following in .env:

  • SECRET_KEY — generate one with python -c "import secrets; print(secrets.token_urlsafe(50))" and keep it out of version control
  • DEBUG=False
  • ALLOWED_HOSTS — your domain(s), comma-separated
  • DATABASE_URL:
    • SQLite: sqlite:////opt/evection/app/db.sqlite3 (note the four slashes for an absolute path)
    • Postgres: postgres://evection:<password>@localhost:5432/evection — create the role and database first:
      sudo -u postgres createuser evection -P
      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, 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

cd /opt/evection/app
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
    /opt/evection/venv/bin/python manage.py migrate
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
    /opt/evection/venv/bin/python manage.py collectstatic --noinput

SQLite only: the search index lives in a SQLite FTS5 table that migrate already created above. If you ever bulk-load articles outside the normal fetch pipeline (e.g. restoring a dump), rebuild it with:

sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
    /opt/evection/venv/bin/python manage.py reindex_search

Postgres needs no equivalent step — its full-text search is computed at query time, not stored in an index.

You don't need to create an admin account by hand: the first time anyone loads the site, Evection's setup wizard creates the first account for you and makes it an instance admin.

6. systemd units

Copy the three unit files from docs/deploy/ into place and adjust paths if you installed somewhere other than /opt/evection:

sudo cp docs/deploy/evection-gunicorn.service \
        docs/deploy/evection-celery-worker.service \
        docs/deploy/evection-celery-beat.service \
        /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now evection-gunicorn evection-celery-worker evection-celery-beat

This runs the Celery worker and beat scheduler as two separate processes, which is the safer default once you might want to scale the worker independently. On a single small host you can combine them into one process instead and skip the evection-celery-beat unit — edit evection-celery-worker.service's ExecStart to add -B:

ExecStart=/opt/evection/venv/bin/celery -A config worker -B --loglevel=info

Check they came up cleanly:

sudo systemctl status evection-gunicorn evection-celery-worker evection-celery-beat
sudo journalctl -u evection-gunicorn -f

7. Reverse proxy

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:

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
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example

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

Open https://your-domain.example/. The setup wizard appears automatically since no account exists yet — create your admin account there. Once any account exists, /setup/ stops being reachable, and you manage further accounts from the "Manage Users" page (visible to admins) or Django's own /admin/.

Once logged in, check the "Dashboard" link in the top nav (admins only) — it surfaces any feeds that are failing to fetch, which is the fastest way to catch a misconfigured feed or an outage at the source.

/health/ is an unauthenticated liveness check (DB connectivity only) — scripts/upgrade.sh uses it to confirm a deploy actually came back up, and it's a reasonable target for an external uptime monitor too.

Backups

  • SQLite: stop the services (or at least gunicorn and the Celery worker) and copy the db.sqlite3 file, or use sqlite3 db.sqlite3 ".backup backup.sqlite3" for a consistent copy without stopping anything.
  • Postgres: pg_dump evection > evection-backup.sql on whatever schedule suits you; no downtime needed.

Either way, also back up your .env file — it's the only copy of SECRET_KEY, and losing it invalidates every existing session and signed cookie.

Upgrading

cd /opt/evection/app
sudo ./scripts/upgrade.sh

That fetches tags, checks out whichever release tag is newest (detached HEAD — see "Releases" above), reinstalls dependencies, migrates, collects static files, restarts whichever of the three services are actually installed, and verifies the app came back up via /health/. It refuses to run if no tags exist yet, and no-ops if you're already on the latest one. Equivalent by hand:

cd /opt/evection/app
git fetch --tags --force
LATEST_TAG="$(git tag --sort=-creatordate | head -n1)"
git checkout --detach "$LATEST_TAG"
chown -R evection:evection /opt/evection/app
sed -i "s/^EVECTION_PWA_CACHE_VERSION=.*/EVECTION_PWA_CACHE_VERSION=$LATEST_TAG/" .env
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
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
    /opt/evection/venv/bin/python manage.py collectstatic --noinput
sudo systemctl restart evection-gunicorn evection-celery-worker evection-celery-beat

To ship a new release, just cut and push a new tag on the machine you build from — the next upgrade.sh run on the server picks it up:

git tag v$(date +%Y.%m.%d)
git push --tags

upgrade.sh sets EVECTION_PWA_CACHE_VERSION in .env to the deployed tag on every run — it's baked into the service worker's cache name, so this forces every installed PWA to drop its old cache instead of serving stale assets after the upgrade. You don't need to bump it by hand.