removing open ports when sibling project removed

skills/sibling-project-format.md

@@ -8,13 +8,14 @@ one with MiniServer's `sibling` command, and from then on MiniServer's
 
 Follow this document when you are working in a sibling repository and need it
 to install and update correctly under MiniServer. A repository needs no
-special files to be installable. It becomes useful by adding two optional
-scripts at its top level:
+special files to be installable. It becomes useful by adding these optional
+files at its top level:
 
-| File         | When it runs                                                 |
-|--------------|--------------------------------------------------------------|
-| `install.sh` | Once, when the user runs `sibling add`, and again if they re-run it |
-| `update.sh`  | On every `update`, right after the repo has been pulled      |
+| File            | When it's used                                               |
+|-----------------|--------------------------------------------------------------|
+| `install.sh`    | Runs once, when the user runs `sibling add`, and again if they re-run it |
+| `update.sh`     | Runs on every `update`, right after the repo has been pulled |
+| `firewall.conf` | Read on `sibling add`, `sibling remove` and every `update` to open the project's ports |
 
 Don't also copy a hook into MiniServer's `updates.d/` for the same project, or
 it updates twice.
@@ -29,7 +30,9 @@ it updates twice.
    already holds a clone of the same URL, runs `git pull --ff-only` there.
 3. If `install.sh` exists, runs `bash install.sh` with the repo folder as the
    working directory. Its input and output are the user's terminal.
-4. Reports success only if every step above succeeded.
+4. If `firewall.conf` exists, opens the ports it lists (see
+   [Firewall](#firewall)).
+5. Reports success only if every step above succeeded.
 
 ### `update`
 
@@ -42,13 +45,14 @@ Next, `updates.d/71-siblings.sh` takes each sibling in alphabetical order and:
 
 A failed pull or a non-zero exit from `update.sh` is printed and listed in
 `update`'s "Done, with errors in: …" summary. Other siblings still update.
-MiniServer's end-of-run hooks (cleanup, reboot check) run after all
-siblings.
+MiniServer's end-of-run hooks (firewall, cleanup, reboot check) run after all
+siblings, so a port added in the latest commit opens in the same update.
 
 ### `sibling remove <name>`
 
-This only deletes `~/.local/share/siblings/<name>`. MiniServer has no uninstall
-step for siblings, so anything `install.sh` set up elsewhere stays.
+This deletes `~/.local/share/siblings/<name>` and closes the ports that only
+its `firewall.conf` asked for. MiniServer has no other uninstall step for
+siblings, so anything `install.sh` set up elsewhere stays.
 
 ## Rules for the Repository
 
@@ -110,6 +114,34 @@ step for siblings, so anything `install.sh` set up elsewhere stays.
 - It's fine to omit `update.sh` if pulling the repo is enough, for example when
   `~/.local/bin` holds symlinks into the repo.
 
+### Firewall
+
+MiniServer runs firewalld, which blocks incoming connections except for the
+services it allows (SSH, mDNS, Cockpit and a few ports). If the project serves
+anything other machines connect to, list its ports in `firewall.conf` at the
+top of the repo:
+
+```bash
+# Ports other machines need to reach. Format: <port>/<protocol> or
+# <first>-<last>/<protocol>, protocol tcp, udp, sctp or dccp.
+FIREWALL_PORTS=(
+  5000/tcp
+)
+
+# Optional: firewalld service names (see `firewall-cmd --get-services`)
+FIREWALL_SERVICES=(
+)
+```
+
+- **Don't open ports from `install.sh` or `update.sh`** with `firewall-cmd`.
+  MiniServer can't close those on `sibling remove`.
+- **Only assign the two arrays.** The file is sourced by bash, but it's read on
+  every `update` and `sibling` command, so it must not do anything else.
+- **Removing an entry closes that port** on the next `update`, unless another
+  project still lists it or it was already open before MiniServer opened it.
+- Containers' published ports with Docker don't need listing: Docker opens
+  them itself.
+
 ### Keep pulls working
 
 `update` pulls with `--ff-only` and never merges or resets. A pull fails if:
@@ -208,6 +240,8 @@ changing.
       and is safe to re-run
 - [ ] `update.sh` (optional) is at the top level, idempotent, doesn't prompt,
       and prints what it's doing
+- [ ] Every port other machines connect to is in `firewall.conf`, and no
+      script runs `firewall-cmd` itself
 - [ ] Scripts find their own files relative to the script and set
       `MINISERVER="$HOME/.local/share/MiniServer"` themselves
 - [ ] Nothing writes to tracked files in the clone, and the default branch is