# 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` 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) |

## 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 linking to the
  museum page, then one post per archived comment, all by the user `Archive`, with the original
  author and date at the top of each post and the original date as the post date. Discussions go
  under three tags (Computers, Consoles, Pongs) that are hidden from "All discussions".
- 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. It writes the map machine → discussion to
  `forum.json`.
- Copied to `../data/forum.json`, that map makes `make content` give every machine a Comments
  tab pointing at 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 Comments tab shows `<forum>/embed/<id>` (Flarum's Embed
  extension) in a frame that follows the height of the thread.

## 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 (outline)

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/`.

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:

       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

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

       php flarum oc:import machines.json --site-url=https://example.org/oldcomputers --map=forum.json

   then bring `forum.json` back as `data/forum.json`, set `params.forum.url`, `make content`,
   `make deploy`.

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.