diff --git a/docs/install.md b/docs/install.md index bcc519f..ee14663 100644 --- a/docs/install.md +++ b/docs/install.md @@ -8,6 +8,27 @@ 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..`); `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 @@ -23,7 +44,9 @@ 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 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 @@ -56,10 +79,13 @@ account: ```bash sudo adduser --system --group --home /opt/evection evection sudo -u evection -H git clone https://github.com//evection.git /opt/evection/app +sudo -u evection -H git -C /opt/evection/app checkout --detach ``` (Swap the `git clone` for however you're distributing releases — a tagged -checkout or an extracted release tarball both work the same way.) +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 @@ -198,6 +224,10 @@ 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 @@ -216,14 +246,18 @@ 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: +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 pull # or: extract the new release over this directory +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 @@ -232,6 +266,14 @@ sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \ 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