Private
Public Access
S4: the throttle keyed on the first X-Forwarded-For entry, which a client or a proxy that appends can choose, and disabled itself entirely when Redis was down. EVECTION_TRUSTED_PROXIES (IPs/CIDRs of your reverse proxy) makes it strict: X-Forwarded-For is only believed when the TCP peer is a trusted proxy, and the rightmost entry that isn't itself a trusted proxy — the address the proxy actually saw — is used instead of the spoofable first one. Unset keeps the previous behavior so existing installs don't suddenly share one bucket behind a proxy, and `manage.py check --deploy` warns (evection.W001) until it's set. During a Redis outage the throttle now falls back to a bounded in-process limiter instead of switching off. C5: /health/ready/ reuses its queue/feed aggregates for 15s (EVECTION_HEALTH_CACHE_SECONDS) so a fast-polling monitor can't create steady load; the database, Redis and poller probes stay live. Docs cover both settings, restricting the endpoint at the proxy, and the tombstone/purge behavior from the previous changes. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
438 lines
20 KiB
Markdown
438 lines
20 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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):
|
|
|
|
```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/<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
|
|
|
|
```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:<password>@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 <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:
|
|
|
|
```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)
|
|
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.
|