Files
Evection/docs/install.md
T
ksmithandClaude Sonnet 5 21c33e8188 Make the reverse proxy a required, pluggable part of every deployment
gunicorn previously only ever bound to a Unix socket, which assumes the
reverse proxy is nginx running on this same host — it can't be reached by
a proxy on a different machine at all (e.g. Nginx Proxy Manager on its own
box), which is this project's actual deployment target. Switch gunicorn to
listening on a plain TCP address instead, controlled by a new
EVECTION_GUNICORN_BIND setting in .env.

install.sh now asks whether the proxy is local or remote and picks a
sensible bind default either way (127.0.0.1:8000 vs 0.0.0.0:8000, with a
reminder to firewall the port in the remote case), and no longer tries to
automate nginx/certbot itself — docs/install.md's new "Reverse proxy"
section covers both shapes instead, since which proxy and where it runs is
the operator's choice, not something this script should assume or set up.
upgrade.sh's health check now curls the TCP bind instead of the old socket
path.

Also add WhiteNoise so gunicorn serves /static/ itself: the old approach
(nginx aliasing the staticfiles directory on disk) silently breaks the
moment the proxy isn't on this host and can't see this filesystem.
nginx.conf.example's own /static/ alias becomes an optional same-host perf
optimization rather than a requirement.

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

318 lines
13 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)
- **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 .
```
## 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 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
```
**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
```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 --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
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:
```bash
git tag v$(date +%Y.%m.%d)
git push --tags
```
Bump `EVECTION_PWA_CACHE_VERSION` in `.env` whenever a release changes cached
static assets (CSS/JS/icons) — it's baked into the service worker's cache name, so
changing it forces every installed PWA to drop its old cache instead of serving
stale assets after the upgrade.