Add install.sh / upgrade.sh to automate the documented deployment steps

Keeps the traditional pip+systemd+nginx deployment (no Docker, per the
original decision) but automates the manual steps already in
docs/install.md instead of leaving them as copy-paste instructions:

- scripts/install.sh: creates the system user, virtualenv, generates
  .env (auto SECRET_KEY, prompts for domain/SQLite-vs-Postgres —
  non-interactive via EVECTION_ALLOWED_HOSTS/EVECTION_DATABASE_URL/etc
  for scripted provisioning), migrates, collects static files, installs
  the systemd units (sed-substituted for the actual install path/user
  rather than hardcoded to /opt/evection), and optionally sets up nginx +
  certbot. Safe to re-run — skips what's already done rather than
  redoing it, and never overwrites an existing .env.
- scripts/upgrade.sh: git pull, reinstall, migrate, collectstatic,
  restart whichever of the three services are actually present (handles
  the combined worker+beat deployment variant too).

docs/install.md now leads with the script as the recommended path, with
the existing step-by-step instructions kept below for anyone who wants
to understand or customize what it's doing.

Verified: shellcheck clean on both scripts (via a throwaway shellcheck-py
venv, since neither apt nor pip --user were available non-interactively);
the systemd-unit and nginx-config sed substitutions produce correct
output against the real template files; the generated .env format
round-trips through `manage.py check` under config.settings.prod without
error. Did not actually run install.sh against a real system — that
creates a system user and installs systemd units, which needs the
person deploying it to run (and review) themselves.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ksmithandClaude Sonnet 5 committed 2026-10-30 22:11:18 -06:00
1 parent 20dd61e938
commit a89f651a71
3 files changed
+287

No files matched your search

+32
View File
@@ -8,6 +8,28 @@ 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.
## Quick install
Once the prerequisites below are in place, `scripts/install.sh` automates
everything from "create a system user" through "systemd units are running" —
and optionally nginx + a Let's Encrypt certificate too. It's interactive
(asks for your domain and database choice) and safe to re-run.
```bash
sudo mkdir -p /opt/evection
sudo git clone <your-fork-or-release-url> /opt/evection/app
cd /opt/evection/app
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 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
deployment before trusting a script with root. Either way, read sections 1
and 4 below first — prerequisites and what `.env` controls.
## 1. Prerequisites ## 1. Prerequisites
- Python 3.11 or 3.12 - Python 3.11 or 3.12
@@ -189,6 +211,16 @@ and losing it invalidates every existing session and signed cookie.
## Upgrading ## Upgrading
```bash
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:
```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 pull # or: extract the new release over this directory
+186
View File
@@ -0,0 +1,186 @@
#!/usr/bin/env bash
# Automates docs/install.md's manual steps: system user, virtualenv, .env,
# migrate/collectstatic, systemd units, and (optionally) nginx + TLS.
#
# Run as root, from inside the checkout you want to serve:
# sudo ./scripts/install.sh
#
# Safe to re-run: it skips steps that are already done (existing user,
# existing venv, existing .env) rather than redoing or overwriting them.
#
# Non-interactive use (e.g. scripted provisioning) — set these before
# running, and the script won't prompt:
# EVECTION_ALLOWED_HOSTS, EVECTION_DATABASE_URL, EVECTION_REDIS_URL,
# EVECTION_USER (defaults to "evection")
set -euo pipefail
if [ "$(id -u)" -ne 0 ]; then
echo "Run this as root: sudo ./scripts/install.sh" >&2
exit 1
fi
APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
EVECTION_HOME="$(dirname "$APP_DIR")"
VENV_DIR="$EVECTION_HOME/venv"
EVECTION_USER="${EVECTION_USER:-evection}"
PYTHON_BIN="${PYTHON_BIN:-python3}"
echo "==> Installing Evection"
echo " App directory: $APP_DIR"
echo " Service user: $EVECTION_USER"
echo " Virtualenv: $VENV_DIR"
echo
# --- 1. Prerequisites -------------------------------------------------
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
echo "'$PYTHON_BIN' not found. Install Python 3.11+ first." >&2
exit 1
fi
PY_VERSION="$("$PYTHON_BIN" -c 'import sys; print("%d.%d" % sys.version_info[:2])')"
PY_MAJOR="${PY_VERSION%%.*}"
PY_MINOR="${PY_VERSION##*.}"
if [ "$PY_MAJOR" -lt 3 ] || { [ "$PY_MAJOR" -eq 3 ] && [ "$PY_MINOR" -lt 11 ]; }; then
echo "Python $PY_VERSION found, but Evection needs 3.11 or newer." >&2
exit 1
fi
for bin in redis-cli nginx; do
if ! command -v "$bin" >/dev/null 2>&1; then
echo "Warning: '$bin' not found on PATH. Install it before going live" \
"(see docs/install.md's prerequisites section: apt install redis-server nginx)." >&2
fi
done
# --- 2. System user -----------------------------------------------------
if ! id -u "$EVECTION_USER" >/dev/null 2>&1; then
echo "==> Creating system user '$EVECTION_USER'"
adduser --system --group --home "$EVECTION_HOME" "$EVECTION_USER"
else
echo "==> System user '$EVECTION_USER' already exists"
fi
chown -R "$EVECTION_USER:$EVECTION_USER" "$APP_DIR"
# --- 3. Virtualenv + install ---------------------------------------------
if [ ! -d "$VENV_DIR" ]; then
echo "==> Creating virtualenv at $VENV_DIR"
sudo -u "$EVECTION_USER" -H "$PYTHON_BIN" -m venv "$VENV_DIR"
fi
echo "==> Installing Evection and its dependencies"
sudo -u "$EVECTION_USER" -H "$VENV_DIR/bin/pip" install --upgrade pip
sudo -u "$EVECTION_USER" -H "$VENV_DIR/bin/pip" install "$APP_DIR"
# --- 4. .env --------------------------------------------------------------
ENV_FILE="$APP_DIR/.env"
if [ ! -f "$ENV_FILE" ]; then
echo "==> Creating $ENV_FILE"
SECRET_KEY="$("$VENV_DIR/bin/python" -c 'import secrets; print(secrets.token_urlsafe(50))')"
ALLOWED_HOSTS="${EVECTION_ALLOWED_HOSTS:-}"
if [ -z "$ALLOWED_HOSTS" ] && [ -t 0 ]; then
read -rp "Domain name(s) this instance will be served from (comma-separated) [localhost]: " ALLOWED_HOSTS
fi
ALLOWED_HOSTS="${ALLOWED_HOSTS:-localhost}"
DATABASE_URL="${EVECTION_DATABASE_URL:-}"
if [ -z "$DATABASE_URL" ] && [ -t 0 ]; then
read -rp "Use PostgreSQL instead of SQLite? [y/N]: " USE_PG
if [[ "${USE_PG:-}" =~ ^[Yy]$ ]]; then
read -rp "Postgres DATABASE_URL (postgres://user:pass@host:5432/dbname): " DATABASE_URL
fi
fi
DATABASE_URL="${DATABASE_URL:-sqlite:///$APP_DIR/db.sqlite3}"
cat > "$ENV_FILE" <<EOF
SECRET_KEY=$SECRET_KEY
DEBUG=False
ALLOWED_HOSTS=$ALLOWED_HOSTS
DATABASE_URL=$DATABASE_URL
REDIS_URL=${EVECTION_REDIS_URL:-redis://localhost:6379/0}
EVECTION_SIGNUP_ENABLED=False
EVECTION_MIN_FETCH_INTERVAL_MINUTES=15
EVECTION_PWA_CACHE_VERSION=v1
EOF
chown "$EVECTION_USER:$EVECTION_USER" "$ENV_FILE"
chmod 600 "$ENV_FILE"
else
echo "==> $ENV_FILE already exists — leaving it alone"
fi
# --- 5. Migrate + static files --------------------------------------------
echo "==> Running migrations"
sudo -u "$EVECTION_USER" -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
"$VENV_DIR/bin/python" "$APP_DIR/manage.py" migrate --noinput
echo "==> Collecting static files"
sudo -u "$EVECTION_USER" -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
"$VENV_DIR/bin/python" "$APP_DIR/manage.py" collectstatic --noinput
# --- 6. systemd units -------------------------------------------------
echo "==> Installing systemd units"
for unit in evection-gunicorn evection-celery-worker evection-celery-beat; do
sed -e "s#/opt/evection#$EVECTION_HOME#g" \
-e "s/User=evection/User=$EVECTION_USER/" \
-e "s/Group=evection/Group=$EVECTION_USER/" \
"$APP_DIR/docs/deploy/${unit}.service" > "/etc/systemd/system/${unit}.service"
done
systemctl daemon-reload
systemctl enable --now evection-gunicorn evection-celery-worker evection-celery-beat
echo
echo "==> Services installed. Checking status..."
systemctl --no-pager status evection-gunicorn evection-celery-worker evection-celery-beat \
|| echo "One or more services didn't start cleanly — see 'journalctl -u evection-gunicorn' etc." >&2
# --- 7. nginx (optional) ---------------------------------------------------
SET_UP_NGINX="${EVECTION_SETUP_NGINX:-}"
if [ -z "$SET_UP_NGINX" ] && [ -t 0 ]; then
echo
read -rp "Set up nginx and an HTTPS certificate now? [y/N]: " SET_UP_NGINX
fi
if [[ "${SET_UP_NGINX:-}" =~ ^[Yy]$ ]]; then
if ! command -v nginx >/dev/null 2>&1; then
echo "nginx isn't installed — install it first (apt install nginx), then" \
"run docs/install.md's nginx section manually." >&2
else
DOMAIN="${EVECTION_DOMAIN:-}"
if [ -z "$DOMAIN" ] && [ -t 0 ]; then
read -rp "Domain name for nginx/TLS (must match a hostname in ALLOWED_HOSTS): " DOMAIN
fi
if [ -z "$DOMAIN" ]; then
echo "No domain given — skipping nginx setup. Run docs/install.md's nginx section manually." >&2
else
sed -e "s/your-domain.example/$DOMAIN/g" \
-e "s#/opt/evection#$EVECTION_HOME#g" \
"$APP_DIR/docs/deploy/nginx.conf.example" > "/etc/nginx/sites-available/evection"
ln -sf /etc/nginx/sites-available/evection /etc/nginx/sites-enabled/evection
if nginx -t; then
systemctl reload nginx
echo "==> nginx configured for $DOMAIN (HTTP only so far)"
if command -v certbot >/dev/null 2>&1; then
certbot --nginx -d "$DOMAIN" || echo "certbot failed — run it manually: certbot --nginx -d $DOMAIN" >&2
else
echo "certbot isn't installed. Install it and run:" \
"apt install certbot python3-certbot-nginx && certbot --nginx -d $DOMAIN" >&2
fi
else
echo "nginx config test failed — not enabling it. Check /etc/nginx/sites-available/evection." >&2
fi
fi
fi
else
echo "==> Skipping nginx — see docs/install.md step 7 to set it up yourself."
fi
echo
echo "==> Done."
echo " Visit the site (once nginx/TLS is in place) — the setup wizard creates your admin account."
echo " To upgrade later: sudo ./scripts/upgrade.sh"
+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# Automates docs/install.md's "Upgrading" section: pull the latest code,
# reinstall dependencies, migrate, collect static files, restart services.
#
# Run as root, from inside an existing install:
# sudo ./scripts/upgrade.sh
#
# Requires scripts/install.sh (or the equivalent manual steps) to have
# been run already, and the app directory to be a git checkout — if you
# deploy from release tarballs instead, extract the new one over this
# directory yourself before running this script.
set -euo pipefail
if [ "$(id -u)" -ne 0 ]; then
echo "Run this as root: sudo ./scripts/upgrade.sh" >&2
exit 1
fi
APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
EVECTION_HOME="$(dirname "$APP_DIR")"
VENV_DIR="$EVECTION_HOME/venv"
EVECTION_USER="${EVECTION_USER:-evection}"
if ! id -u "$EVECTION_USER" >/dev/null 2>&1; then
echo "System user '$EVECTION_USER' doesn't exist — is Evection installed?" \
"Run scripts/install.sh first." >&2
exit 1
fi
if [ ! -x "$VENV_DIR/bin/python" ]; then
echo "No virtualenv found at $VENV_DIR — is Evection installed?" \
"Run scripts/install.sh first." >&2
exit 1
fi
echo "==> Upgrading Evection in $APP_DIR"
if [ -d "$APP_DIR/.git" ]; then
echo "==> Pulling latest code"
sudo -u "$EVECTION_USER" -H git -C "$APP_DIR" pull --ff-only
else
echo "$APP_DIR isn't a git checkout — extract the new release over it" \
"yourself, then re-run this script to finish the upgrade." >&2
exit 1
fi
echo "==> Installing updated dependencies"
sudo -u "$EVECTION_USER" -H "$VENV_DIR/bin/pip" install --upgrade "$APP_DIR"
echo "==> Running migrations"
sudo -u "$EVECTION_USER" -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
"$VENV_DIR/bin/python" "$APP_DIR/manage.py" migrate --noinput
echo "==> Collecting static files"
sudo -u "$EVECTION_USER" -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
"$VENV_DIR/bin/python" "$APP_DIR/manage.py" collectstatic --noinput
echo "==> Restarting services"
for unit in evection-gunicorn evection-celery-worker evection-celery-beat; do
if systemctl list-unit-files "${unit}.service" 2>/dev/null | grep -q "${unit}.service"; then
systemctl restart "$unit"
fi
done
echo
echo "==> Upgrade complete."
echo " If this release changed cached static assets (CSS/JS/icons), bump"
echo " EVECTION_PWA_CACHE_VERSION in $APP_DIR/.env and restart evection-gunicorn"
echo " again so installed PWAs drop their old cache instead of serving stale assets."