Document the tag-based release/deploy flow in docs/install.md

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>
This commit is contained in:
ksmithandClaude Sonnet 5 committed 2026-10-31 08:29:21 -06:00
1 parent 3ba46f9d49
commit 3e627b1ef8
1 file changed
+49 -7
+49 -7
View File
@@ -8,6 +8,27 @@ below runs directly on the host.
Both SQLite and PostgreSQL are fully supported. Steps that differ are marked Both SQLite and PostgreSQL are fully supported. Steps that differ are marked
**SQLite** / **Postgres**; everything else applies to both. **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 ## Quick install
Once the prerequisites below are in place, `scripts/install.sh` automates 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 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 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 you want to run it manually, customize something, or just understand the
@@ -56,10 +79,13 @@ account:
```bash ```bash
sudo adduser --system --group --home /opt/evection evection 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 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 (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 ## 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 surfaces any feeds that are failing to fetch, which is the fastest way to catch a
misconfigured feed or an outage at the source. 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 ## Backups
- **SQLite**: stop the services (or at least gunicorn and the Celery worker) and - **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 sudo ./scripts/upgrade.sh
``` ```
That pulls the latest code (if `/opt/evection/app` is a git checkout — That fetches tags, checks out whichever release tag is newest (detached
extract a release tarball over it yourself first otherwise), reinstalls HEAD — see "Releases" above), reinstalls dependencies, migrates, collects
dependencies, migrates, collects static files, and restarts whichever of static files, restarts whichever of the three services are actually
the three services are actually installed. Equivalent by hand: 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 ```bash
cd /opt/evection/app 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 /opt/evection/venv/bin/pip install .
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \ sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
/opt/evection/venv/bin/python manage.py migrate /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 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 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 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 changing it forces every installed PWA to drop its old cache instead of serving