From 041f79259448506d1c97c7b7298209d6ae79721b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Wed, 13 Mar 2024 19:10:51 +0100
Subject: [PATCH] Website: document Flamenco's MQTT support

---
 .../usage/manager-configuration/_index.md     | 21 ++++++
 .../usage/manager-configuration/mqtt.md       | 66 +++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 web/project-website/content/usage/manager-configuration/mqtt.md

diff --git a/web/project-website/content/usage/manager-configuration/_index.md b/web/project-website/content/usage/manager-configuration/_index.md
index e85ccc65..edae1e55 100644
--- a/web/project-website/content/usage/manager-configuration/_index.md
+++ b/web/project-website/content/usage/manager-configuration/_index.md
@@ -18,10 +18,12 @@ This is an example `flamenco-manager.yaml` file:
 ```yaml
 _meta:
   version: 3
+
 manager_name: Flamenco Manager
 database: flamenco-manager.sqlite
 listen: :8080
 autodiscoverable: true
+
 local_manager_storage_path: ./flamenco-manager-storage
 shared_storage_path: /path/to/storage
 shaman:
@@ -30,10 +32,12 @@ shaman:
     period: 24h0m0s
     maxAge: 744h0m0s
     extraCheckoutPaths: []
+
 task_timeout: 10m0s
 worker_timeout: 1m0s
 blocklist_threshold: 3
 task_fail_after_softfail_count: 3
+
 variables:
   blender:
     values:
@@ -47,9 +51,26 @@ variables:
     values:
       - platform: all
         value: -b -y
+
+mqtt:  # See 'MQTT Configuration' below.
+  client:
+    broker: "tcp://mqttserver.local:1883"
+    username: "username"
+    password: "your-password-here"
+    topic_prefix: flamenco
+
 ```
 
 The usual way to create a configuration file is simply by starting Flamenco
 Manager. If there is no config file yet, it will start the setup assistant to
 create one. If for any reasons the setup assistant is not usable for you, you
 can use the above example to create `flamenco-manager.yaml` yourself.
+
+## MQTT Configuration
+
+The `mqtt` section is completely optional. If you do not know what it's for, just leave it out.
+
+For more information about the built-in MQTT client, see
+[Manager Configuration: MQTT][mqtt].
+
+[mqtt]: {{< ref "usage/manager-configuration/mqtt.md" >}}
diff --git a/web/project-website/content/usage/manager-configuration/mqtt.md b/web/project-website/content/usage/manager-configuration/mqtt.md
new file mode 100644
index 00000000..03bbfd84
--- /dev/null
+++ b/web/project-website/content/usage/manager-configuration/mqtt.md
@@ -0,0 +1,66 @@
+---
+title: "Manager Configuration: MQTT"
+titleTOC: MQTT
+---
+
+Flamenco Manager can send its internal events to an [MQTT][mqtt] broker. Other
+MQTT clients can listen to those events, in order to respond to what happens on
+the render farm.
+
+[mqtt]: https://en.wikipedia.org/wiki/MQTT
+
+*MQTT support was introduced in Flamenco 3.5.*
+
+## Configuration
+
+To enable MQTT functionality, place a section like this in your
+`flamenco-manager.yaml` file and restart Flamenco Manager:
+
+```yaml
+mqtt:
+  client:
+    broker: "tcp://mqttserver.local:1883"
+    username: "username"
+    password: "your-password-here"
+    topic_prefix: flamenco
+```
+
+<div>
+<style>
+  .gdoc-markdown dl dt {
+    margin-top: 0.1rem;
+  }
+</style>
+
+`broker`
+: The URL of the MQTT Broker. Supports `tcp://` and `ws://` URLs.
+
+`username` & `password`
+: The credentials used to connect to the MQTT Broker. For anonymous access, just
+  remove those two keys.
+
+`topic_prefix`
+: Topic prefix for the MQTT events sent to the broker. Defaults to `flamenco`.
+  For example, job updates are sent to the `flamenco/jobs` topic.
+
+</div>
+
+## MQTT Topics
+
+The following topics will be used by Flamenco:
+
+| Description                      | MQTT topic                       | JSON event payload        |
+|----------------------------------|----------------------------------|---------------------------|
+| Manager startup/shutdown         | `/lifecycle`                     | `EventLifeCycle`          |
+| Farm status                      | `/status`                        | `EventFarmStatus`         |
+| Job update                       | `/jobs`                          | `EventJobUpdate`          |
+| Task update                      | `/jobs/{job UUID}`               | `EventTaskUpdate`         |
+| Worker update                    | `/workers`                       | `EventWorkerUpdate`       |
+| Worker Tag update                | `/workertags`                    | `EventWorkerTagUpdate`    |
+| Last rendered image              | `/last-rendered`                 | `EventLastRenderedUpdate` |
+| Job-specific last rendered image | `/jobs/{job UUID}/last-rendered` | `EventLastRenderedUpdate` |
+
+For the specification of the JSON sent in the MQTT events, use the above table
+and then look up the type description in the [OpenAPI specification][oapi].
+
+[oapi]: https://projects.blender.org/studio/flamenco/src/branch/main/pkg/api/flamenco-openapi.yaml