Files
Evection/docs/install.md
T
ksmithandClaude Sonnet 5 a89f651a71 Add install.sh / upgrade.sh to automate the documented deployment steps
Keeps the traditional pip+systemd+nginx deployment (no Docker, per the
original decision) but automates the manual steps already in
docs/install.md instead of leaving them as copy-paste instructions:

- scripts/install.sh: creates the system user, virtualenv, generates
  .env (auto SECRET_KEY, prompts for domain/SQLite-vs-Postgres —
  non-interactive via EVECTION_ALLOWED_HOSTS/EVECTION_DATABASE_URL/etc
  for scripted provisioning), migrates, collects static files, installs
  the systemd units (sed-substituted for the actual install path/user
  rather than hardcoded to /opt/evection), and optionally sets up nginx +
  certbot. Safe to re-run — skips what's already done rather than
  redoing it, and never overwrites an existing .env.
- scripts/upgrade.sh: git pull, reinstall, migrate, collectstatic,
  restart whichever of the three services are actually present (handles
  the combined worker+beat deployment variant too).

docs/install.md now leads with the script as the recommended path, with
the existing step-by-step instructions kept below for anyone who wants
to understand or customize what it's doing.

Verified: shellcheck clean on both scripts (via a throwaway shellcheck-py
venv, since neither apt nor pip --user were available non-interactively);
the systemd-unit and nginx-config sed substitutions produce correct
output against the real template files; the generated .env format
round-trips through `manage.py check` under config.settings.prod without
error. Did not actually run install.sh against a real system — that
creates a system user and installs systemd units, which needs the
person deploying it to run (and review) themselves.

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

239 lines
8.9 KiB
Markdown

# 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.
## Quick install
Once the prerequisites below are in place, `scripts/install.sh` automates
everything from "create a system user" through "systemd units are running" —
and optionally nginx + a Let's Encrypt certificate too. It's interactive
(asks for your domain and database choice) and safe to re-run.
```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 — you don't need to create it or clone as that user 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
- 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/<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
```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 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 ./scripts/upgrade.sh
```
That pulls the latest code (if `/opt/evection/app` is a git checkout —
extract a release tarball over it yourself first otherwise), reinstalls
dependencies, migrates, collects static files, and restarts whichever of
the three services are actually installed. Equivalent by hand:
```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.