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 <noreply@anthropic.com>
This commit is contained in:
ksmithandClaude Sonnet 5.5 committed 2026-11-01 11:59:03 -07:00
1 parent 698940763f
commit 10ba491e10
1 file changed
+18 -3
+18 -3
View File
@@ -105,9 +105,17 @@ than a branch.)
```bash ```bash
cd /opt/evection/app cd /opt/evection/app
sudo -u evection -H python3 -m venv /opt/evection/venv 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 ## 4. Configure
Copy the example environment file and edit it: Copy the example environment file and edit it:
@@ -377,12 +385,13 @@ Equivalent by hand:
```bash ```bash
cd /opt/evection/app cd /opt/evection/app
git fetch --tags --force git fetch --tags # deliberately not --force: see below
LATEST_TAG="$(git tag --sort=-creatordate | head -n1)" LATEST_TAG="$(git tag --sort=-creatordate | head -n1)"
git checkout --detach "$LATEST_TAG" git checkout --detach "$LATEST_TAG"
chown -R evection:evection /opt/evection/app chown -R evection:evection /opt/evection/app
sed -i "s/^EVECTION_PWA_CACHE_VERSION=.*/EVECTION_PWA_CACHE_VERSION=$LATEST_TAG/" .env 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 \ 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
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \ 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 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 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: from — the next `upgrade.sh` run on the server picks it up: