Files
Evection/docs/install.md
T
ksmithandClaude Sonnet 5 3f6474ce94 Add hardening and deployment: admin dashboard, security headers, install docs
Adds an admin-only dashboard (apps/core) surfacing feeds that are failing to
fetch, with error messages, subscriber counts, and a one-click retry that
resets backoff and re-queues the fetch.

Hardens config/settings/prod.py with the remaining standard Django security
settings (HSTS preload, nosniff, referrer-policy, frame-options, SameSite
cookies) plus a Content-Security-Policy header via django-csp, as a second
layer behind nh3's HTML sanitization of feed content.

Adds docs/install.md (pip + gunicorn + systemd + nginx, SQLite and Postgres
both covered) plus the systemd units and nginx snippet it references,
LICENSE (AGPL-3.0-or-later, matching pyproject.toml), and an updated README.

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

7.6 KiB

Installing Evection

Evection is a traditional Python/Django application: pip install, a WSGI server (gunicorn), a Celery worker + beat scheduler for background feed polling, and an nginx reverse proxy in front of it. There's no Docker image for v1 — everything below runs directly on the host.

Both SQLite and PostgreSQL are fully supported. Steps that differ are marked SQLite / Postgres; everything else applies to both.

1. Prerequisites

  • Python 3.11 or 3.12
  • 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)
  • nginx (or another reverse proxy)
  • A domain name pointed at the host, if you want this reachable outside your LAN

Debian/Ubuntu example for the non-Python pieces:

sudo apt install redis-server nginx
# 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

(Swap the git clone for however you're distributing releases — a tagged checkout or an extracted release tarball both work the same way.)

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 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 — see config/settings/prod.py if you need to adjust it for your proxy setup.

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. nginx

Copy docs/deploy/nginx.conf.example to /etc/nginx/sites-available/evection, adjust server_name and the certificate paths, then enable it:

sudo cp docs/deploy/nginx.conf.example /etc/nginx/sites-available/evection
sudo ln -s /etc/nginx/sites-available/evection /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Get a TLS certificate (Let's Encrypt via certbot is the easiest path):

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example

Evection's prod settings enable SECURE_SSL_REDIRECT and HSTS by default, so plan to have TLS working 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.

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 -u evection -H git pull   # or: extract the new release over this directory
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

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.