Private
Public Access
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:
1 parent
3ba46f9d49
commit
3e627b1ef8
1 file changed
+49
-7
+49
-7
@@ -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<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
|
||||
@@ -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/<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.)
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user