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
|
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
|
||||||
|
|||||||
Reference in new issue
Block a user