website/forum/README.md

# Forum and comments (Flarum)

The forum is a separate PHP application ([Flarum](https://flarum.org/) 2, PHP 8.3+, MariaDB or
MySQL). It is not part of the static build: the site only links to it and shows its threads in a
frame.

| Path | Role |
|---|---|
| `extension/` | Flarum extension `oc/flarum-museum`: the `oc:import` and `oc:pages` commands, original author names, the look of embedded threads |
| `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

- `../oc/scripts/06_forum.py` writes `import/machines.json`: one entry per machine with its
  archived comments, oldest first.
- `php flarum oc:import` creates one discussion per machine: an opening post by the user
  `Archive` linking to the museum page, then one post per archived comment, dated as the
  original. Each comment is posted by an account standing for its original author, shown under
  the name used on the old site ("darius (croatia)"); the same name on several machines is one
  account. These accounts are in the group "Original site" (a badge on their posts), have a
  random password and an undeliverable address, so nobody can log in as them. Discussions go
  under three tags (Computers, Consoles, Pongs) that are hidden from "All discussions".
- Original names are stored as nicknames (Nicknames extension, which must be enabled) and shown
  by the display-name driver `museum` of this extension, which the import selects: the stock
  nickname driver would remove the brackets.
- The command records what it imported (table `oc_threads`) and skips it on later runs, so it
  can be run again when new machines arrive. `--replace` deletes and re-imports the imported
  threads that have no reply from a real member (their thread numbers change). It writes the map machine → discussion to
  `forum.json`.
- Copied to `../data/forum.json`, that map makes `make content` link every machine to its thread (`forum_thread` in the page front matter); the old comments are
  then no longer written into the pages.
- With `params.forum.url` set, the bottom of the machine's pages shows `<forum>/embed/<id>` (Flarum's Embed
  extension) in a frame that follows the height of the thread.

## News posts

`php flarum oc:pages` creates one discussion per news post under the tag News (listed with the
other forum topics, unlike the machine threads), opened by the system account `News` with a
link to the post. `make forum-sync` in the website repository drives it: `tools/forum_sync.py`
sends the list of published posts to the forum host (`FORUM_RUN`, `FORUM_DIR`, `FORUM_PHP` in
the Makefile) and stores the answer in `data/forum_pages.json`. `make deploy` runs it first, so
a new post gets its discussion when it is published. A post that is renamed gets a new
discussion; a retitled one keeps its discussion and its old title there.

## Local test

    make forum-up        # http://localhost:8081, admin / adminadmin (first start takes a minute)
    make forum-import    # export + import; safe to repeat

To see it in the site, copy `forum/import/forum.json` to `data/forum.json`, run `make content`,
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

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/`,
served at `https://barbel.synology.me/oldcomputers-forum`.

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.

Installed there on 2026-10-11. Things specific to this server:

- command-line PHP is `/usr/local/bin/php84`, and needs `-d memory_limit=512M` for Flarum's
  console (`cache:clear` runs out of memory with the default 128M);
- MariaDB 10 listens on port 3307: database host `127.0.0.1:3307`;
- SSH is on port 27 and has no `scp`/`sftp`: send a file with
  `ssh -p 27 user@host 'cat > /volume2/web/oldcomputers-forum/storage/machines.json' < forum/import/machines.json`;
- the forum folder is `/volume2/web/oldcomputers-forum`.

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, anti-spam 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/`.
   While the forum is copied but not installed, keep it closed: put the bundle's `.htaccess`
   aside as `.htaccess.forum` and use a one-line `.htaccess` containing `Require all denied`.
   Swap them back just before installing.
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 Nicknames, Embed and "Old-Computers museum" (admin panel, or
   `php flarum extension:enable` with `flarum-nicknames`, `flarum-embed`, `oc-museum`). Tags is enabled by default.
6. In the admin panel: e-mail settings (registration confirms addresses by e-mail). Enable the
   spam filter (`fof-anti-spam`). Schedule a database dump.
7. Import, from a shell on the server (SSH, or a one-off Task Scheduler script run as `http`),
   in the forum folder (copy `import/machines.json` there first):

       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: dump the database, rebuild the bundle, unpack it over
the existing folder (it contains no `config.php`), then `php flarum migrate` and
`php flarum cache:clear`:

    ssh -p 27 user@host 'cd /volume2/web/oldcomputers-forum && tar xzf - --no-overwrite-dir \
        --no-same-owner --no-same-permissions --exclude=./storage --exclude=./public/assets' \
        < forum/import/forum.tar.gz

Unpacking resets the folders it touches to plain Unix permissions on the Synology (even with
`--no-overwrite-dir`), which drops the ACL entry that lets `http` write: the forum then answers
500. Repair, as the folder's owner (the forum folder, `public`, `public/assets`, `vendor`,
`packages`):

    /usr/syno/bin/synoacltool -add <folder> "user:http:allow:rwxpdDaARWc--:fd--"

and add the same entry for your own account and `group:administrators` right after, or the
folder is closed to you. Do not use `-enforce-inherit` or `-copy` on a plain-permission file:
they leave it with an empty ACL (no access at all; `chmod 644`/`755` brings it back). The
simpler alternative, used for the WordPress folder: plain permissions with the group `http`
(`chgrp -R http . && chmod -R g+rwX .`).

The bundle includes the spam filter `fof/anti-spam` (StopForumSpam check at registration, tools
to remove a spammer); enable it with `php flarum extension:enable fof-anti-spam` (it needs
`flarum-flags` and `flarum-approval`).

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.