# 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: ```bash 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: ```bash sudo adduser --system --group --home /opt/evection evection sudo -u evection -H git clone https://github.com//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 ```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:@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 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 ```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. nginx Copy `docs/deploy/nginx.conf.example` to `/etc/nginx/sites-available/evection`, adjust `server_name` and the certificate paths, then enable it: ```bash 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): ```bash 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 ```bash 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.