From 19e23aee6f5fc5ea02b5452f0037734049755036 Mon Sep 17 00:00:00 2001 From: Jens Ahrensfeld Date: Sun, 26 Jul 2026 18:06:55 +0200 Subject: [PATCH] SETUP.md: rebase fresh-install baseline from 22.04 to 24.04 Document the two third-party-repo gaps a fresh 24.04 build actually needs (ondrej/php for the dyndns app's php7.4, rspamd.com for a current rspamd) - both were previously undocumented and both bit this exact host during its own 22.04->24.04 upgrade. --- SETUP.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/SETUP.md b/SETUP.md index 14f3540..80f6251 100644 --- a/SETUP.md +++ b/SETUP.md @@ -1,9 +1,16 @@ # alpha.jayfield.org — Fresh-Install Setup Guide -This is a from-scratch runbook for reproducing this host: Ubuntu 22.04 LTS -running authoritative DNS, a full mail stack, Apache-fronted web services, -and a Docker layer for containerized apps (Portainer, Nextcloud). It's -written in build order — each section depends on the ones before it. +This is a from-scratch runbook for reproducing this host: Ubuntu 24.04 LTS +(Noble Numbat) running authoritative DNS, a full mail stack, Apache-fronted +web services, and a Docker layer for containerized apps (Portainer, +Nextcloud, Gitea). It's written in build order — each section depends on +the ones before it. + +This host itself was originally built on 22.04 and upgraded in place to +24.04 on 2026-07-26 (see `TODO.md` for the full rollout and the two +post-upgrade breakages it turned up, `fail2ban` and `rspamd`) — a fresh +build today should start directly on 24.04 rather than replaying that +upgrade path. Reference: `README.md` documents the *current, live* state of this exact server. This file documents *how to get there* from nothing. When the two @@ -239,7 +246,22 @@ reconfiguring first, without a hard cutover). ## 3. Mail stack (Postfix + Dovecot + rspamd + fail2ban) +**Use the `rspamd.com` repo, not `apt install rspamd` straight from +Ubuntu's own archive** — noble's native `rspamd` package is older than +upstream's own repo build (this host runs `4.1.3` from `rspamd.com`). +This isn't just a version-freshness preference: this exact gap caused a +real incident during this host's 22.04→24.04 upgrade, where +`do-release-upgrade` silently *removed* rspamd entirely (its apt source +was in the old, disabled deb822 `.sources` format and didn't carry +forward) rather than upgrading it — `systemctl status rspamd` still +showed old cached "active" state for a while after, masking that it +had stopped scanning mail at all. Add the repo for your release +explicitly, verify it's actually enabled, then install: ```bash +curl -sS https://rspamd.com/apt-stable/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/rspamd.gpg +echo "deb [signed-by=/usr/share/keyrings/rspamd.gpg] http://rspamd.com/apt-stable/ $(lsb_release -cs) main" | \ + sudo tee /etc/apt/sources.list.d/rspamd.sources.list +sudo apt update sudo apt install -y postfix postfix-mysql mariadb-server \ dovecot-core dovecot-imapd dovecot-lmtpd dovecot-managesieved \ dovecot-mysql dovecot-sieve \ @@ -249,6 +271,12 @@ sudo apt install -y postfix postfix-mysql mariadb-server \ During the `postfix` package install prompt, pick "Internet Site", `mail.` as the system mail name. +After any future release upgrade, don't trust `systemctl is-active +rspamd` alone — confirm it's genuinely scanning mail with `rspamc +symbols <<< "test"` (a phantom-active-but-not-scanning rspamd is +exactly what happened here; this check is now automated in +`scripts/alpha/sanity-check.sh`, which runs after every boot). + ### MySQL: virtual mailbox schema ```bash @@ -590,10 +618,33 @@ sudo postfix check && sudo postconf -n # sanity check ## 4. Web (Apache + Let's Encrypt) ```bash -sudo apt install -y apache2 certbot python3-certbot-apache libapache2-mod-php7.4 +sudo apt install -y apache2 certbot python3-certbot-apache sudo a2enmod ssl proxy proxy_http rewrite headers ``` +**`php7.4` isn't in noble's default archives** — this host's `dyndns` +app (see below) is written against 7.4, not noble's own default PHP. +Pull it from the `ondrej/php` PPA instead, targeting `noble` (not +`focal`/`jammy`, despite `ppa.launchpad.net`'s URLs and some +mirrors/filenames still saying "focal" from older releases of this same +PPA — check the actual `Suites:` line, not the filename): +```bash +sudo add-apt-repository -y ppa:ondrej/php +sudo apt update +sudo apt install -y libapache2-mod-php7.4 +``` +Confirm the source is genuinely built for this release before trusting +it, not just present: `apt-cache policy libapache2-mod-php7.4` should +show a `noble` (not `jammy`) candidate. **This host's own 22.04→24.04 +upgrade left this exact package on stale jammy-built binaries for a +while** — `do-release-upgrade` repoints the PPA's `Suites:` to the new +codename automatically, but doesn't by itself pull down matching +rebuilt packages for third-party PPAs; a plain `apt full-upgrade` after +the release upgrade completes is what actually finishes the job. Check +`apt list --upgradable` after any future release upgrade rather than +assuming a completed `do-release-upgrade` run means everything is +current. + For each subdomain (static site, dyndns, mail webmail-proxy, any Docker-backed app): create `/etc/apache2/sites-available/.conf` with a `:80` vhost, `a2ensite`, then let certbot handle TLS + the redirect: