From 06f336a8b90d52bba8af8cb5ae2369e15fedfdc4 Mon Sep 17 00:00:00 2001
From: Bruno Pagno <brunopagno@proton.me>
Date: Wed, 14 Jan 2026 12:18:49 +0100
Subject: [PATCH] Include and enable Hocuspocus (Collaboration Server) (#135)

* include hocuspocus and respective configuration

* include defaults to hocuspocus setup

* Update release version

Co-authored-by: Kabiru Mwenja <makabby@gmail.com>

* update readme with explicit info about secret & localhost

---------

Co-authored-by: Kabiru Mwenja <makabby@gmail.com>
---
 .env.example             |  2 ++
 README.md                | 12 ++++++++++++
 docker-compose.yml       | 12 ++++++++++++
 proxy/Caddyfile.template |  2 ++
 4 files changed, 28 insertions(+)

diff --git a/.env.example b/.env.example
index 5a863dd..36e8956 100644
--- a/.env.example
+++ b/.env.example
@@ -17,3 +17,5 @@ RAILS_MIN_THREADS=4
 RAILS_MAX_THREADS=16
 PGDATA="/var/lib/postgresql/data"
 OPDATA="/var/openproject/assets"
+COLLABORATIVE_SERVER_URL=ws://localhost:8080/hocuspocus
+COLLABORATIVE_SERVER_SECRET=secret12345
diff --git a/README.md b/README.md
index 636179c..cece692 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,18 @@ If this happens during `docker compose pull` this is simply a warning as well.
 But it will result in the command's exit code to be a failure even though all images are pulled.
 To prevent this you can add the `--ignore-buildable` option, running `docker compose pull  --ignore-buildable`.
 
+### Collaboration server
+
+The collaboration server is enabled by default when setting up this application.
+
+> Important! Make sure to override the default secret by adjusting the docker-compose file or setting the `COLLABORATIVE_SERVER_SECRET` variable.
+
+When running it in *localhost* it's necessary to make a few adjustments:
+
+1. Either define a local alias (adding an entry to your hosts file) or setup HTTPS/SSL
+2. Define the `OPENPROJECT_HOST__NAME`, and the `COLLABORATIVE_SERVER_URL` in your .env file (you can look at .env.example for reference)
+3. Restart the containers
+
 ### HTTPS/SSL
 
 By default OpenProject starts with the HTTPS option **enabled**, but it **does not** handle SSL termination itself. This
diff --git a/docker-compose.yml b/docker-compose.yml
index ad9c198..8015518 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -19,6 +19,8 @@ x-op-app: &app
     RAILS_CACHE_STORE: "memcache"
     OPENPROJECT_CACHE__MEMCACHE__SERVER: "cache:11211"
     OPENPROJECT_RAILS__RELATIVE__URL__ROOT: "${OPENPROJECT_RAILS__RELATIVE__URL__ROOT:-}"
+    OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__URL: "${COLLABORATIVE_SERVER_URL:-wss://${OPENPROJECT_HOST__NAME}/hocuspocus}"
+    OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__SECRET: "${COLLABORATIVE_SERVER_SECRET:-OVERRIDE_ME_PLEASE}"
     DATABASE_URL: "${DATABASE_URL:-postgres://postgres:p4ssw0rd@db/openproject?pool=20&encoding=unicode&reconnect=true}"
     RAILS_MIN_THREADS: ${RAILS_MIN_THREADS:-4}
     RAILS_MAX_THREADS: ${RAILS_MAX_THREADS:-16}
@@ -63,6 +65,7 @@ services:
   web:
     <<: *app
     command: "./docker/prod/web"
+    hostname: "${OPENPROJECT_HOST__NAME:-localhost:8080}"
     networks:
       - frontend
       - backend
@@ -114,3 +117,12 @@ services:
     restart: on-failure
     networks:
       - backend
+
+  hocuspocus:
+    image: openproject/hocuspocus:release-38128805
+    environment:
+      SECRET: ${COLLABORATIVE_SERVER_SECRET:-OVERRIDE_ME_PLEASE}
+    networks:
+      - backend
+      - frontend
+    <<: *restart_policy
diff --git a/proxy/Caddyfile.template b/proxy/Caddyfile.template
index 7de7b97..d4844b9 100644
--- a/proxy/Caddyfile.template
+++ b/proxy/Caddyfile.template
@@ -1,4 +1,6 @@
 :80 {
+    reverse_proxy /hocuspocus* hocuspocus:1234
+
     reverse_proxy * http://${APP_HOST}:8080 {
         # The following directives are needed to make the proxy forward explicitly the X-Forwarded-* headers. If unset,
         # Caddy will reset them. See: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#defaults