Rewrote README documentation

playbooks/linux/ubuntu-server/nextcloud_full_deployment/README.txt

@@ -1,42 +1,98 @@
 ---- Welcome ----
 
-This is a full-stack Nextcloud deployment combined with a hardnening and a Collabora CODE server setup and integration into Nextcloud.
+This is a full-stack Nextcloud deployment combined with hardening, a Collabora CODE server for
+in-browser document editing, and a Nextcloud Talk High-Performance Backend (HPB) for group calls.
+An Open-Xchange mail connector is also planned (see "Playbooks" below for its current status).
 
 The minimum setup of this deployment would be a single server (this context wasn't tested yet).
-The optimal setup would be two servers, a server for the Nextcloud and a server for the CODE server.
+The optimal setup uses one server per role:
 
-The current playbook stack is made for a theoratical infinite amount of Nextcloud instance setups (not load balanced or anything in that direction) and a single server for Collabora CODE.
+    - Nextcloud                    (Apache + PHP + MariaDB)
+    - Collabora CODE               (document editing backend)
+    - Nextcloud Talk HPB           (NATS + Janus Gateway + signaling server, via Docker)
 
-Currently this setup assumes that the server for both Nextcloud and Collabora CODE is Ubuntu 26.04 server. This can be changed but hasn't been tested yet and required some tinkering (e.g. in the deploy_collabora_code.yml file for the APT sources).
+The current playbook stack is made for a theoretical infinite amount of Nextcloud instance setups
+(not load balanced or anything in that direction) and a single server each for Collabora CODE and
+the Talk HPB.
+
+Currently this setup assumes that every server is Ubuntu 24.04 server. This can be changed but
+hasn't been tested yet and requires some tinkering (e.g. in the deploy_collabora_code.yml file for
+the APT sources).
+
+---- Directory structure ----
+
+    /nextcloud_full_deployment
+    | - README.txt                             (this file)
+    | - deploy_hardened_nextcloud.yml
+    | - deploy_collabora_code.yml
+    | - connect_nextcloud_collabora.yml
+    | - deploy_nc_talk_hpb.yml
+    | - connect_nextcloud_open-xchange.yml
+    | - /inventory
+        | - hosts.ini
+    | - /vars
+        | - shared_vars.yml.example
+
+---- Requirements ----
+
+On the Ansible control node:
+    - Ansible collections: community.general, community.mysql, community.docker
+
+On every managed host:
+    - Ubuntu 24.04 server (see note above about other versions)
+    - User with sudo rights, reachable over SSH
 
 ---- Quickstart ----
 
 First of all specify your hosts in the inventory folder.
-Please also add the username and password as host vars in the two inventory files.
+Please also add the username and password as host vars in the inventory file.
 
     /nextcloud_full_deployment
     | - /inventory
         | - hosts.ini
 
-After that is done go change all the variables that will be used in the setup according to your needs.
+The inventory has one host group per role: [nextcloud], [collabora_code] and
+[nextcloud_talk_hpb]. A single host can be a member of more than one group if you want to
+co-locate roles on one server.
+
+After that is done, copy vars/shared_vars.yml.example to vars/shared_vars.yml and go change all
+the variables in it according to your needs. Every secret in that file (database password, admin
+password, Collabora admin password, Talk HPB signaling/TURN/hash/block secrets) ships with a
+"ChangeMe..." placeholder - replace all of them before deploying.
 
     /nextcloud_full_deployment
     | - vars
         | - shared_vars.yml
 
-When you are done with preparing your deployment, you can start the deployment.
+When you are done preparing your deployment, you can start it. Run the playbooks against hosts in
+this order, since each one depends on the previous:
 
-The basic Nextcloud deployment is done by running:
+1. Nextcloud itself (Apache, PHP, MariaDB, TLS, hardening, fail2ban):
-ansible-playbook deploy_hardened_nextcloud.yml -i inventory --ask-become-pass
+   ansible-playbook deploy_hardened_nextcloud.yml -i inventory --ask-become-pass
 
-Collabora CODE is deployed with:
+2. Collabora CODE (document editing backend):
-ansible-playbook deploy_collabora_code.yml -i inventory --ask-become-pass
+   ansible-playbook deploy_collabora_code.yml -i inventory --ask-become-pass
 
-To connect Collabora CODE and your Nextcloud instances use:
+3. Connect Collabora CODE to your Nextcloud instance(s):
-ansible-playbook connect_nextcloud_collabora.yml -i inventory --ask-become-pass
+   ansible-playbook connect_nextcloud_collabora.yml -i inventory --ask-become-pass
 
+4. Nextcloud Talk High-Performance Backend (NATS + Janus + signaling server, via Docker):
+   ansible-playbook deploy_nc_talk_hpb.yml -i inventory --ask-become-pass
 
-You can debug all the playbooks by using this commmand.
+   This playbook only sets up the backend itself. Nextcloud does not pick it up automatically -
+   finish the connection by hand on each Nextcloud instance under
+   Administration -> Talk -> High-performance backend:
+       Signaling server URL: https://<nc_talk_hpb_domain>/standalone-signaling
+       Shared secret:        nc_talk_hpb_signaling_secret (from shared_vars.yml)
+       TURN server:          <nc_talk_hpb_domain>:3478, protocols UDP and TCP
+       TURN secret:          nc_talk_hpb_turn_secret (from shared_vars.yml)
+
+5. Open-Xchange mail connector - not yet implemented. connect_nextcloud_open-xchange.yml
+   currently only contains the sudo-rs workaround boilerplate shared by every playbook in this
+   repo; the openxchange_* variables in shared_vars.yml.example are reserved for it but are not
+   consumed by any task yet.
+
+You can debug all the playbooks by using this command.
 ansible-playbook <playbook_file.yml> -i inventory --ask-become-pass -vv
 
 

playbooks/linux/ubuntu-server/nextcloud_full_deployment/vars/shared_vars.yml.example

@@ -42,6 +42,27 @@ fail2ban_dir: "/etc/fail2ban"
 
 nc_talk_hpb_domain: "talk-hpb.cloud.example.com"
 
+# Where the NATS/Janus/Signaling Docker Compose stack and its config live on the HPB host.
+nc_talk_hpb_install_dir: "/opt/hpb"
+
+# Talk HPB TLS certificate paths (used by the Apache reverse proxy).
+nc_talk_hpb_ssl_cert: "/etc/ssl/certs/nc-talk-hpb-selfsigned.crt"
+nc_talk_hpb_ssl_key:  "/etc/ssl/private/nc-talk-hpb-selfsigned.key"
+
+# UDP port range Janus uses for WebRTC media (RTP). Must also be reachable through the firewall.
+nc_talk_hpb_rtp_port_range: "20000-40000"
+
+# Admin key for the Janus VideoRoom plugin (lets the signaling server manage rooms via the admin API).
+nc_talk_hpb_janus_admin_key: "ChangeMe1234_"
+
+# Shared secrets for the signaling server. Generate each with the given command and paste the result here.
+# turn/signaling/hash: openssl rand -hex 32   (64 hex chars)
+# block:               openssl rand -hex 16   (32 hex chars — MUST be exactly 32, 48 or 64 hex chars or the signaling server refuses to start)
+nc_talk_hpb_turn_secret: "ChangeMe_RunOpensslRandHex32"
+nc_talk_hpb_signaling_secret: "ChangeMe_RunOpensslRandHex32"
+nc_talk_hpb_hash_key: "ChangeMe_RunOpensslRandHex32"
+nc_talk_hpb_block_key: "ChangeMe_RunOpensslRandHex16"
+
 ########################################
 # Collabora CODE
 ########################################