From 10ba491e10f9d7b541a6cade1c98a9aba142af14 Mon Sep 17 00:00:00 2001 From: Keith Smith Date: Sun, 1 Nov 2026 11:59:03 -0700 Subject: [PATCH] Make the manual install/upgrade docs match the hardened scripts (R2-C4, #44) docs/install.md still showed 'git fetch --tags --force' and a bare 'pip install .', reintroducing the rewritten-tag and unpinned-dependency risks the scripts closed. The manual steps now use a non-forced fetch (with an explanation of what a clobber error means) and the hash-pinned requirements.txt install followed by pip install --no-deps. Co-Authored-By: Claude Sonnet 5.5 --- docs/install.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/install.md b/docs/install.md index a9fe374..87fa4f0 100644 --- a/docs/install.md +++ b/docs/install.md @@ -105,9 +105,17 @@ than a branch.) ```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 . +sudo -u evection -H /opt/evection/venv/bin/pip install --upgrade pip +sudo -u evection -H /opt/evection/venv/bin/pip install --require-hashes -r requirements.txt +sudo -u evection -H /opt/evection/venv/bin/pip install --no-deps . ``` +`requirements.txt` pins every dependency to an exact, hash-verified version, so +two installs of the same release get identical dependency code and a tampered +package fails the hash check instead of installing. The app itself goes in +with `--no-deps` afterwards. (Don't use a bare `pip install .` — it re-resolves +version ranges at install time, which is what the lock file exists to avoid.) + ## 4. Configure Copy the example environment file and edit it: @@ -377,12 +385,13 @@ Equivalent by hand: ```bash cd /opt/evection/app -git fetch --tags --force +git fetch --tags # deliberately not --force: see below LATEST_TAG="$(git tag --sort=-creatordate | head -n1)" git checkout --detach "$LATEST_TAG" chown -R evection:evection /opt/evection/app sed -i "s/^EVECTION_PWA_CACHE_VERSION=.*/EVECTION_PWA_CACHE_VERSION=$LATEST_TAG/" .env -sudo -u evection -H /opt/evection/venv/bin/pip install . +sudo -u evection -H /opt/evection/venv/bin/pip install --require-hashes -r requirements.txt +sudo -u evection -H /opt/evection/venv/bin/pip install --no-deps --upgrade . 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 \ @@ -390,6 +399,12 @@ sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \ sudo systemctl restart evection-gunicorn evection-celery-worker evection-celery-beat ``` +A plain `git fetch --tags` refuses to move a tag you already have onto a +different commit — the sign of a rewritten or tampered release. If it fails +with "would clobber existing tag", stop and find out why before deploying; +don't reach for `--force`, which would silently follow the rewritten tag into +production (`scripts/upgrade.sh` stops there too). + 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: