From d6962c41130664d75ba8797544442f2f087f84aa Mon Sep 17 00:00:00 2001
From: Samuel Weirich <4281791+SamuelWei@users.noreply.github.com>
Date: Wed, 12 Feb 2025 10:08:40 +0100
Subject: [PATCH] Improve order of recording install docs

---
 .../08-advanced/03-recording.md               | 74 +++++++++----------
 1 file changed, 34 insertions(+), 40 deletions(-)

diff --git a/docs/docs/administration/08-advanced/03-recording.md b/docs/docs/administration/08-advanced/03-recording.md
index ca6b48638..9816d0c36 100644
--- a/docs/docs/administration/08-advanced/03-recording.md
+++ b/docs/docs/administration/08-advanced/03-recording.md
@@ -33,6 +33,16 @@ addgroup pilos-spool --gid 2000
 
 ## Transferring recordings
 
+### Post publish script
+
+To transfer the recording files to PILOS for permanent storage and serving, you need to set up a post_publish script.
+
+You can find an example post_publish script in the `bigbluebutton` directory of the PILOS repository (`bigbluebutton/pilos_post_publish.rb`).
+This script needs to be installed on all BBB-Servers in the `/usr/local/bigbluebutton/core/scripts/post_publish` directory.
+
+You also need to configure the script using the config file `pilos.yml` in the `bigbluebutton` directory of the PILOS repository (`bigbluebutton/pilos.yml`).
+Install the file in the `/etc/bigbluebutton/recording/` directory.
+
 To transfer the recording files to PILOS you have two options:
 
 - Shared storage
@@ -42,7 +52,7 @@ To transfer the recording files to PILOS you have two options:
 
 To use shared storage, you need to mount the shared storage to the BBB-Servers and PILOS.
 
-**On the BBB Server** you need to set the mount point in the `spool_dir` setting of the `pilos.yml` file.
+**On the BBB Server** you need to set the mount point in the `spool_dir` setting of the `/etc/bigbluebutton/recording/pilos.yml` file.
 
 ```yaml
 spool_dir: /mnt/storage/recordings-spool
@@ -101,36 +111,42 @@ To further secure the transfer, you can later restrict the user to only run the
 
 1. Create an ssh key for the bigbluebutton user on the BBB-Server.
 
-```bash
-su - bigbluebutton -s /bin/bash -c "ssh-keygen -t ed25519 -N '' -f ~/.ssh/pilos && cat ~/.ssh/pilos.pub"
-```
+    ```bash
+    su - bigbluebutton -s /bin/bash -c "ssh-keygen -t ed25519 -N '' -f ~/.ssh/pilos && cat ~/.ssh/pilos.pub"
+    ```
 
 2. Edit the `.ssh/config` file of the bigbluebutton user and add the following lines.
 
-```bash
-su - bigbluebutton -s /bin/bash -c "nano ~/.ssh/config"
-```
+    ```bash
+    su - bigbluebutton -s /bin/bash -c "nano ~/.ssh/config"
+    ```
 
-```
-Host pilos
-    HostName pilos.example.com
-    Port 22
-    User pilos-spool
-    IdentityFile ~/.ssh/pilos
-```
+    ```
+    Host pilos
+        HostName pilos.example.com
+        Port 22
+        User pilos-spool
+        IdentityFile ~/.ssh/pilos
+    ```
+
+    This will tell the BBB-Server to use the ssh key and the `pilos-spool` user when connecting to the PILOS server.
+    It will also create an alias for the PILOS server, so you can use `pilos` instead of the full hostname.
 
-This will tell the BBB-Server to use the ssh key and the `pilos-spool` user when connecting to the PILOS server.
-It will also create an alias for the PILOS server, so you can use `pilos` instead of the full hostname.
+3. Adjust the `spool_dir` setting in the `/etc/bigbluebutton/recording/pilos.yml` file to the rsync destination.
+    ```yaml
+    spool_dir: pilos:/
+    ```
 
 **On the PILOS server:**
 
 The public key of the bigbluebutton user needs to be added to the `~/.ssh/authorized_keys` file of the `pilos-spool` user.
 
 ```bash
-su - pilos-spool -s /bin/bash -c "mkdir ~/.ssh && chmod 700 ~/.ssh && nano ~/.ssh/authorized_keys"
+su - pilos-spool -s /bin/bash -c "mkdir -m 700 ~/.ssh && nano ~/.ssh/authorized_keys"
 ```
 
-You can paste the public key from the BBB-Server and restrict the key to only run the rsync command in the recordings-spool directory:
+You can paste the public key from the BBB-Server and restrict the key to only run the rsync command in the recordings-spool directory.
+In this example we assume PILOS is installed in the `/srv/pilos` directory, adjust this according to your installation.
 
 ```
 # Example key restricted to rsync and the path of the recordings-spool directory
@@ -166,28 +182,6 @@ docker compose exec app cat storage/recordings-spool/test.txt
 docker compose exec app rm storage/recordings-spool/test.txt
 ```
 
-## Post publish script
-
-To transfer the recording files to PILOS for permanent storage and serving, you need to setup a post_publish script.
-
-You can find an example post_publish script in the `bigbluebutton` directory of the PILOS repository.
-This script needs to be installed on all BBB-Servers in the `/usr/local/bigbluebutton/core/scripts/post_publish` directory.
-
-You also need configure the script using the config file in the `bigbluebutton` directory of the PILOS repository.
-Adjust and install the file in the `/etc/bigbluebutton/recording/` directory.
-
-If you are using the shared storage, you need to set the `spool_dir` setting in the `pilos.yml` file to the local mountpoint on the BBB-Server.
-
-```yaml
-spool_dir: /mnt/storage/recordings-spool
-```
-
-If you are using rsync over ssh, you need to set the `spool_dir` setting in the `pilos.yml` file to the rsync destination.
-
-```yaml
-spool_dir: pilos:/
-```
-
 ### Cleanup
 
 BigBlueButton processes all recording formats independently of each other.