diff --git a/docs/install.md b/docs/install.md index ce559d9..bcc519f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -8,6 +8,28 @@ 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. +## 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 /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 - Python 3.11 or 3.12 @@ -189,6 +211,16 @@ and losing it invalidates every existing session and signed cookie. ## 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 cd /opt/evection/app sudo -u evection -H git pull # or: extract the new release over this directory diff --git a/scripts/install.sh b/scripts/install.sh new file mode 100755 index 0000000..4e34bdf --- /dev/null +++ b/scripts/install.sh @@ -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" < $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" diff --git a/scripts/upgrade.sh b/scripts/upgrade.sh new file mode 100755 index 0000000..6cf3cad --- /dev/null +++ b/scripts/upgrade.sh @@ -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."