Private
Public Access
install.sh and upgrade.sh deploy git tags, not branch tips, but the docs still described git pull/clone-and-run. Add a "Releases" section explaining the v<year>.<month>.<day> tagging convention and that a tag must exist before the first production install, update the manual upgrade steps to match what upgrade.sh actually does (fetch tags, checkout latest), and mention the /health/ endpoint upgrade.sh verifies against. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
281 lines
10 KiB
Markdown
281 lines
10 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
|
|
- 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
|
|
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.
|