# 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.11.1` (`v..`, no zero padding); a second release the same day is `v2026.11.1.2`, a third `v2026.11.1.3`, and so on. `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: ```bash git tag v$(date +%Y.%-m.%-d) # a later release the same day: append .2, .3, ... 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. ```bash sudo mkdir -p /opt/evection sudo git clone /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): ```bash 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: ```bash sudo adduser --system --group --home /opt/evection evection sudo -u evection -H git clone https://github.com//evection.git /opt/evection/app sudo -u evection -H git -C /opt/evection/app checkout --detach ``` (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 ```bash cd /opt/evection/app sudo -u evection -H python3 -m venv /opt/evection/venv sudo -u evection -H /opt/evection/venv/bin/pip install --upgrade pip sudo -u evection -H /opt/evection/venv/bin/pip install --require-hashes -r requirements.txt sudo -u evection -H /opt/evection/venv/bin/pip install --no-deps . ``` `requirements.txt` pins every dependency to an exact, hash-verified version, so two installs of the same release get identical dependency code and a tampered package fails the hash check instead of installing. The app itself goes in with `--no-deps` afterwards. (Don't use a bare `pip install .` — it re-resolves version ranges at install time, which is what the lock file exists to avoid.) ## 4. Configure Copy the example environment file and edit it: ```bash 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:@localhost:5432/evection` — create the role and database first: ```bash 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_TRUSTED_PROXIES` — the IP address (or CIDR, comma-separated for more than one) of your reverse proxy, as gunicorn sees it connecting. The login throttle only believes `X-Forwarded-For` from these addresses, and takes the address your proxy actually saw rather than the first entry (which a client can forge). Leave it unset and it falls back to trusting that header from anyone, which is only safe while nothing but your proxy can reach gunicorn; `manage.py check --deploy` warns until it's set. With Nginx Proxy Manager on another host, use that host's address (check `ss -tn` on this machine while loading the site if you're not sure what gunicorn sees). How often every feed is polled is a site-wide setting (Django admin → Site settings), not a `.env` value — `EVECTION_MIN_FETCH_INTERVAL_MINUTES` only sets a floor under it, so it can't be configured lower than that without editing `.env`. 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 ```bash 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: ```bash 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`: ```bash 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: ```bash 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: ```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 sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.example ``` `127.0.0.1:8000` is still a TCP port any local process can connect to (any other user or container sharing this host, not just nginx). If you want gunicorn reachable by nothing but the proxy, bind it to a Unix socket instead: set `EVECTION_GUNICORN_BIND=unix:/run/evection/gunicorn.sock` in `.env`, add `RuntimeDirectory=evection` under `[Service]` in `evection-gunicorn.service` (creates `/run/evection`, owned by the `evection` user, on every start), and point nginx's `proxy_pass` at `http://unix:/run/evection/gunicorn.sock:;` instead of the TCP address — nginx needs read/write access to that socket, so either run nginx's worker as a user in the `evection` group or adjust the directory's permissions accordingly. This is optional hardening, not required. **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. This isn't optional hardening: Evection trusts `X-Forwarded-Proto` and `X-Forwarded-For` from whoever can reach this port at all (see `config/settings/prod.py` and `apps/accounts/views.py`'s login rate limiter), so anyone who can reach it directly can set those headers themselves and be trusted as if they were the proxy. With ufw, that's: ```bash sudo ufw allow from to any port 8000 proto tcp sudo ufw deny 8000/tcp ``` (order matters — the `allow from` rule must be added before the blanket `deny`). Point the proxy's upstream/forward target at `this-host:8000`, and make sure it **overwrites** `X-Forwarded-For` with its own view of the client's address rather than appending to whatever the client already sent — a proxy that appends lets a client forge a trusted-looking first hop. It must also set `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, including that overwrite-not- append distinction for `X-Forwarded-For`. **Nginx Proxy Manager specifically:** NPM's generated config already sets `X-Forwarded-For` to the appending (unsafe) form by default — override it per proxy host rather than editing NPM's own templates: open the proxy host entry for Evection, go to its **Advanced** tab, and add this to the **Custom Nginx Configuration** box: ```nginx proxy_set_header X-Forwarded-For $remote_addr; ``` This lands inside NPM's own `location` block, after its default headers, so nginx uses this one (the last `proxy_set_header` for a given name in the same block wins) — no edit to any file NPM manages, and it survives NPM regenerating its config. Save, and NPM reloads nginx for you. If something else sits in front of NPM itself (a CDN, another load balancer, Cloudflare, ...), `$remote_addr` at NPM's layer is that upstream's address, not the original client — forward whatever *that* layer's own trusted client-IP header says instead. 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. Point an external uptime monitor at `/health/ready/` instead. It returns 503 with a per-check breakdown when any of these fail: - `database` and `redis` — reachable. - `poll_heartbeat` — the background poller ticked in the last five minutes (proves Celery beat is scheduling *and* a worker is consuming). - `queue_depth` — no more than 1000 tasks waiting in the Celery queue (workers aren't keeping up, or aren't running). - `recent_fetch_success` — at least one feed has been fetched successfully within three poll intervals (minimum 30 minutes), so "scheduled but every fetch is failing" is caught. A brand-new install gets that long before it counts as stale. - `feed_failures` — no more than half of your active feeds are failing, once you have at least four (a handful of dead feeds is normal; most of them failing at once points at your server, DNS, or outbound network). The payload also reports `queue_depth`, `active_feeds`, `failing_feeds`, and the age of the last successful fetch, so you can graph them. The queue and feed figures are reused for 15 seconds (`EVECTION_HEALTH_CACHE_SECONDS`, 0 disables it) so a fast-polling monitor can't turn them into steady database load; the database, Redis and poller checks are always live. The endpoint is unauthenticated, so if you'd rather not expose those numbers publicly, restrict `/health/ready/` to your monitor's address at the proxy. **Retention.** By default every fetched article is kept forever. In the Django admin, "Site settings" has a *Retention days* field: set it to delete articles fetched longer ago than that, nightly (03:30 UTC, via Celery beat). Articles anyone has starred or saved for later are always kept; read state and tags for deleted articles go with them. A small record (feed and entry id) is kept for each deleted article so a feed that still lists it can't bring it back as new and unread — those records are themselves removed after a year, so an entry a feed is *still* publishing a year after it was purged (with no publish date, or a recent one) can come back as new. Entries whose own publish date is already older than the window aren't fetched in the first place. A large first purge works in time-boxed runs (about four minutes each) that queue their own continuation, so it never monopolises a worker. The dashboard shows the article count and the age of the oldest one, so you can see what retention is doing. **SQLite.** SQLite installs run in WAL mode with a 20-second busy timeout (set automatically in `config/settings/base.py`) so gunicorn, the Celery worker, and the full-text-search triggers can share the file without "database is locked" errors. That's plenty for a personal or small-team instance; for many users or a very large archive, use PostgreSQL (its search uses a stored, GIN-indexed vector kept current by a trigger, added by migration automatically). ## 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 ```bash 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: ```bash cd /opt/evection/app git fetch --tags # deliberately not --force: see below 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 --require-hashes -r requirements.txt sudo -u evection -H /opt/evection/venv/bin/pip install --no-deps --upgrade . 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 ``` A plain `git fetch --tags` refuses to move a tag you already have onto a different commit — the sign of a rewritten or tampered release. If it fails with "would clobber existing tag", stop and find out why before deploying; don't reach for `--force`, which would silently follow the rewritten tag into production (`scripts/upgrade.sh` stops there too). 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: ```bash git tag v$(date +%Y.%-m.%-d) # a later release the same day: v2026.11.1.2, .3, ... 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.