Private
Public Access
On Debian/Ubuntu, python3-venv (ensurepip support) is a separate package from python3 itself, and apt installing just python3 leaves venv creation failing partway through install.sh — after the system user, chown, and git checkout have all already happened. Check for it up front alongside the Python version check, and document the apt package in install.md's prerequisites. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
283 lines
11 KiB
Markdown
283 lines
11 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.
|
|
|
|
## 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" —
|
|
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, 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)
|
|
- 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 (swap `python3.13-venv` for
|
|
whatever `python3 --version` reports on your system):
|
|
|
|
```bash
|
|
sudo apt install redis-server nginx 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 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.
|
|
|
|
`/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
|
|
sudo -u evection -H git fetch --tags --force
|
|
LATEST_TAG="$(sudo -u evection -H git tag --sort=-creatordate | head -n1)"
|
|
sudo -u evection -H git checkout --detach "$LATEST_TAG"
|
|
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.
|