INSTALL.md: complete package list with purpose table, step 0 (clone), architecture sketch, Go toolchain notes, keep svxdr/ out of the webroot

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

INSTALL.md

@@ -1,9 +1,26 @@
-# SvxPortal web — installation HOWTO
+# SvxPortal — installation HOWTO
 
-This is the **web front-end only** for a SvxReflector: node map, monitor,
-last-heard, talkgroup list, user accounts and the reflector admin pages.
-It is plain HTML/JavaScript plus a small PHP backend that stores accounts in
-Redis. No build step, no framework, no composer.
+SvxPortal is the web front-end for a SvxReflector: node map, monitor,
+last-heard, talkgroup list, user accounts and reflector admin pages. It has
+two parts, both in this repository:
+
+- **the web**: plain HTML/JavaScript plus a small PHP backend that keeps
+  accounts in Redis. No build step, no framework, no composer.
+- **svxdr**: a Go daemon that reads the reflector's `/status` and serves the
+  live data the dashboard shows. One `go build`, no other build tools.
+
+How the pieces connect:
+
+```
+browser ──HTTPS──> nginx ──> static files + PHP-FPM ──> Redis   (accounts, sessions, bans)
+                     │
+                     └── /svxportal/api/ ──> svxdr nodelist :8098
+                                                  └──> svxdr proxy :8090 ──> svxreflector HTTP_SRV_PORT :8099
+```
+
+Steps in order: 0 get the code, 1 packages, 2 web files, 3 Redis, 4 PHP-FPM,
+5 web config, 6 talkgroup file, 7 nginx + TLS, 8 first admin, 9 svxdr.
+Step 10 is optional. Step 11 is troubleshooting.
 
 What you need on the server:
 
@@ -15,7 +32,8 @@ What you need on the server:
 | Redis 6+ | stores accounts, sessions, bans, talkgroup requests |
 | A way to send e-mail | signup verification and password reset (local MTA **or** an SMTP relay, see step 5) |
 | TLS certificate | the session cookie is `Secure`; login does not work over plain HTTP |
-| A running SvxReflector | we use [GeuReflector](https://github.com/audric/GeuReflector) (SvxReflector with trunking); `install/svxreflector.conf.example` is for that build |
+| A running SvxReflector | we use [GeuReflector](https://github.com/audric/GeuReflector) (SvxReflector with trunking); build it per its own README. `install/svxreflector.conf.example` is for that build |
+| Go 1.24+ | to compile svxdr (step 9). Debian 13 ships it; on Debian 12 / Ubuntu 24.04 the packaged Go is older but fetches the right toolchain itself, see step 9 |
 
 Everything below assumes Debian 12/13 or Ubuntu 24.04, PHP 8.4 and that the
 site will live at `https://svxportal.example.com`. Replace the host name
@@ -23,20 +41,45 @@ everywhere you see it.
 
 ---
 
-## 1. Packages
+## 0. Get the code
 
 ```bash
-sudo apt install nginx php8.4-fpm php8.4-redis php8.4-mbstring php8.4-cli redis-server certbot openssl
+sudo apt install git
+cd ~ && git clone https://git.sa7aux.se/bjorne/svx-web-pub.git svxportal
+cd svxportal
 ```
 
+All paths below are relative to this checkout unless they start with `/`.
+
+## 1. Packages
+
+Everything the web, Redis, TLS and svxdr need, in one go:
+
+```bash
+sudo apt install nginx php8.4-fpm php8.4-redis php8.4-mbstring php8.4-cli \
+                 redis-server certbot openssl rsync curl python3 sudo golang-go
+```
+
+| Package | Used by |
+|---------|---------|
+| `nginx` | web server |
+| `php8.4-fpm`, `php8.4-redis`, `php8.4-mbstring`, `php8.4-cli` | PHP backend; `-cli` for `svx-mkadmin.php` (step 8). `openssl`/`json`/`session` are built into Debian's PHP |
+| `redis-server` | account store; also provides the `redis-server@` instance template (step 3) |
+| `certbot` | Let's Encrypt certificate (step 7) |
+| `openssl` | CSR parsing in the certificate admin pages, password generation |
+| `rsync` | copying the web files into the webroot (step 2) |
+| `curl`, `python3` | the optional talkgroup sync timer (step 6b) and the checks in this guide |
+| `golang-go` | compiles svxdr (step 9) |
+
 Check the PHP version you actually got (`php -v`) and use that number instead
-of `8.4` in the file names below.
+of `8.4` in the file names below. On Debian 12 the PHP is 8.2; the portal is
+developed on 8.4, so prefer Debian 13 or the `packages.sury.org` PHP repo.
 
 ## 2. Copy the web files
 
 ```bash
 sudo mkdir -p /var/www/html/svxportal
-sudo rsync -a --exclude .git --exclude install --exclude INSTALL.md ./ /var/www/html/svxportal/
+sudo rsync -a --exclude .git --exclude install --exclude svxdr --exclude INSTALL.md --exclude README.md ./ /var/www/html/svxportal/
 sudo chown -R www-data:www-data /var/www/html/svxportal
 sudo find /var/www/html/svxportal -type d -exec chmod 2775 {} +
 sudo find /var/www/html/svxportal -type f -exec chmod 0644 {} +
@@ -250,12 +293,25 @@ in the browser console).
 
 ### Build
 
+`svxdr/go.mod` asks for Go 1.24. Debian 13 ships 1.24. Debian 12 and Ubuntu
+24.04 ship an older `golang-go`, but since Go 1.21 the `go` command downloads
+the required toolchain by itself on first build, so the packaged Go works as
+long as the box has internet access. The build also downloads the two Go
+dependencies (go-redis, paho-mqtt) from proxy.golang.org.
+
 ```bash
-sudo apt install golang-go          # Go 1.24 or newer
+go version                          # any 1.21+ is fine, see above
 cd svxdr && CGO_ENABLED=0 go build -trimpath -o svxdr . && cd ..
+ls -l svxdr/svxdr                   # ~12 MB static binary
 sudo install -m0755 svxdr/svxdr /usr/local/bin/svxdr
 ```
 
+No internet on the server? Build on any machine with Go (same command, add
+`GOOS=linux GOARCH=amd64` or `arm64`) and copy the single binary over.
+
+If `go build` complains about the toolchain, install Go from
+<https://go.dev/dl/> instead of the distro package and rerun.
+
 ### Configure
 
 ```bash