Forum: PHP 8.4 test image, server bundle, install notes for the test server

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YDRjtmAiNpo5mK5N3d7QwZ

Makefile

@@ -7,7 +7,7 @@ PAGEFIND ?= npx -y pagefind@1
 DEPLOY_DIR ?= /run/user/$(shell id -u)/gvfs/smb-share:server=barbel-lescar,share=web/oldcomputers
 DEPLOY_URL ?= https://barbel.synology.me/oldcomputers/
 
-.PHONY: content build check serve deploy post forum-up forum-import forum-down
+.PHONY: content build check serve deploy post forum-up forum-import forum-down forum-bundle
 
 content:       ## regenerate content/ and static/media/ from the extraction repo
 	python3 $(OC)/scripts/05_hugo.py --target $(CURDIR) $(if $(wildcard data/forum.json),--forum)
@@ -46,3 +46,9 @@ forum-import:  ## export the archived comments and import them into the test for
 
 forum-down:    ## stop the test forum (forum-db volume keeps its data)
 	$(FORUM) down
+
+forum-bundle:  ## build forum/import/forum.tar.gz: Flarum + extension, to copy to the server
+	mkdir -p forum/import
+	$(FORUM) build flarum
+	docker run --rm --entrypoint /bundle.sh -v $(CURDIR)/forum/docker/bundle.sh:/bundle.sh:ro \
+		-v $(CURDIR)/forum/extension:/extension:ro -v $(CURDIR)/forum/import:/out forum-flarum

forum/README.md

@@ -7,8 +7,8 @@ frame.
 | Path | Role |
 |---|---|
 | `extension/` | Flarum extension `oc/flarum-museum`: the `oc:import` command and the look of embedded threads |
-| `docker/`, `docker-compose.yml` | local test forum |
-| `import/` | not versioned: `machines.json` (export from the extraction repo) and `forum.json` (thread map) |
+| `docker/`, `docker-compose.yml` | local test forum; `docker/bundle.sh` packages the server bundle |
+| `import/` | not versioned: `machines.json` (export from the extraction repo), `forum.json` (thread map), `forum.tar.gz` (server bundle) |
 
 ## How comments work
 
@@ -36,36 +36,44 @@ To see it in the site, copy `forum/import/forum.json` to `data/forum.json`, run
 and build with `HUGO_PARAMS_FORUM_URL=http://localhost:8081 hugo server`. Do not commit a
 `data/forum.json` made from the test forum: its thread numbers are not those of the real one.
 
-## Server install (outline)
+## Server install
 
 The forum must live **outside** the folder `make deploy` writes to (that folder is synchronised
-with deletion). On the test server: `web/oldcomputers-forum/`, next to `web/oldcomputers/`.
+with deletion). On the test server: `web/oldcomputers-forum/`, next to `web/oldcomputers/`,
+served at `https://barbel.synology.me/oldcomputers-forum`.
 
-1. PHP 8.3 or newer with curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer,
-   zip; an empty database and a user for it.
-2. `composer create-project flarum/flarum oldcomputers-forum "^2.0"`, then in that folder
-   `composer require flarum/embed "^2.0"`.
-3. Web server: requests that are not files go to `public/index.php`, and nothing outside `public/`
-   is served. Flarum ships rules for Apache (`public/.htaccess`) and nginx (`.nginx.conf`); a
-   sub-folder install is described in the Flarum documentation ("Customizing paths").
-4. Open the forum address and finish the installer (database, administrator account).
-5. Copy `extension/` to `packages/oc-museum/` in the forum folder, then:
+Checked on the test server (2026-10-11): PHP 8.4 (FPM) with every extension Flarum needs, Apache
+2.4 behind nginx, `.htaccess` rewriting active. Files copied over the network share are **not
+writable by the web server user `http`**, and the share does not let permissions be changed.
 
-       composer config repositories.oc path "packages/*"
-       composer require "oc/flarum-museum:*@dev"
-       php flarum migrate
-       php flarum extension:enable flarum-tags
-       php flarum extension:enable flarum-embed
-       php flarum extension:enable oc-museum
+No Composer is needed on the server: `make forum-bundle` builds `forum/import/forum.tar.gz`, a
+complete Flarum 2 tree (PHP 8.4) with the Embed and museum extensions and a top-level
+`.htaccess` that routes every request into `public/`, so `config.php`, `storage/` and `vendor/`
+are never served. This layout is tested in the local image.
 
+1. Create an empty MariaDB database and a user for it.
+2. Unpack the bundle into `web/oldcomputers-forum/`.
+3. Give the user `http` write access to that folder and everything in it (File Station →
+   Properties → Permissions, or `chown -R http:http` over SSH). Flarum writes `config.php`,
+   `storage/` and `public/assets/`.
+4. Install. Either open the forum address and fill the installer (database, administrator), or
+   over SSH, as `http`, in the forum folder: `php flarum install --file=install.yml` (format in
+   `docker/entrypoint.sh`). Do not leave the folder online uninstalled: whoever opens the
+   installer first becomes its administrator.
+5. Enable the extensions Embed and "Old-Computers museum" (admin panel, or
+   `php flarum extension:enable flarum-embed` and `oc-museum`). Tags is enabled by default.
 6. In the admin panel: e-mail settings (registration confirms addresses by e-mail), and a spam
    filter extension. Schedule a database dump.
-7. Import: copy `import/machines.json` to the server and run
+7. Import, over SSH in the forum folder (copy `import/machines.json` there first):
 
-       php flarum oc:import machines.json --site-url=https://example.org/oldcomputers --map=forum.json
+       php flarum oc:import machines.json --site-url=https://barbel.synology.me/oldcomputers --map=forum.json
 
    then bring `forum.json` back as `data/forum.json`, set `params.forum.url`, `make content`,
    `make deploy`.
 
+To update the forum or the extension later: rebuild the bundle, unpack it over the existing
+folder (it contains no `config.php` and no user data), then `php flarum migrate` and
+`php flarum cache:clear`.
+
 The forum and the site should share one domain: logging in from the embedded thread relies on
 the forum's cookie, which browsers restrict across domains.

forum/docker/Dockerfile

@@ -1,5 +1,5 @@
-# Local test forum: Flarum 2 on Apache. Not the production install (see forum/README.md).
-FROM php:8.3-apache
+# Local test forum: Flarum 2 on Apache, PHP 8.4 like the test server. Not the production install (see forum/README.md).
+FROM php:8.4-apache
 RUN apt-get update && apt-get install -y --no-install-recommends git unzip libzip-dev libpng-dev libjpeg-dev libfreetype6-dev \
     && docker-php-ext-configure gd --with-jpeg --with-freetype \
     && docker-php-ext-install pdo_mysql gd zip \

forum/docker/bundle.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Runs inside the forum image: writes /out/forum.tar.gz, a complete Flarum tree with the museum
+# extension, ready to copy to a server that has PHP but no Composer (see forum/README.md).
+set -e
+cd /var/www/flarum
+rm -rf packages/oc-museum && mkdir -p packages && cp -r /extension packages/oc-museum
+composer config repositories.oc '{"type": "path", "url": "packages/*", "options": {"symlink": false}}'
+composer require --no-interaction --update-no-dev --optimize-autoloader "oc/flarum-museum:*@dev" >/dev/null
+# the forum lives in a sub-folder of the web root: route everything into public/, so that
+# config.php, storage/ and vendor/ are never served
+printf '# Everything is served from public/: nothing else of the forum is reachable.\nRewriteEngine On\nRewriteRule ^(.*)$ public/$1 [L]\n' > .htaccess
+tar czf /out/forum.tar.gz --exclude=./config.php --exclude='./storage/logs/*' --exclude='./storage/cache/*' --exclude='./storage/sessions/*' .
+chown "$(stat -c %u:%g /out)" /out/forum.tar.gz