/health/ready/ proved beat and a worker were alive but not that fetching worked: every feed could be failing, or the queue could be hours behind, and it would still report ok. apps.core.health adds three checks: Celery queue depth (real Redis list length, over 1000 fails), a successful fetch within three poll intervals (30 min minimum, with a grace period for a brand-new install), and the share of active feeds failing (over half, once there are at least four). The payload also reports queue depth, active/failing feed counts, and the age of the last successful fetch. Verified against real Redis with queued Celery tasks, and the suite on PostgreSQL. docs/install.md lists each check. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
18 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
venvmodule (Debian/Ubuntu split this into a separatepython3.X-venvpackage — 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 withpython -c "import secrets; print(secrets.token_urlsafe(50))"and keep it out of version controlDEBUG=FalseALLOWED_HOSTS— your domain(s), comma-separatedDATABASE_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
- SQLite:
REDIS_URL—redis://localhost:6379/0is fine for a single-host installEVECTION_GUNICORN_BIND— theaddress:portgunicorn listens on; see "Reverse proxy" below for how to pick this
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
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
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:
sudo ufw allow from <proxy-host-ip> 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:
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:
databaseandredis— 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.
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, and entries whose own publish date is already older than the window aren't fetched in the first place. 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.sqlite3file, or usesqlite3 db.sqlite3 ".backup backup.sqlite3"for a consistent copy without stopping anything. - Postgres:
pg_dump evection > evection-backup.sqlon 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.