feat: Added a script to run OO locally for local dev (#4680)

Author: shepilov

docs/docker.md

@@ -62,23 +62,79 @@ docker run --rm -it -p 8080:8080 -v "$(pwd)/build":/data/cozy-app/***my-app*** c
 
 ## Only-Office document server
 
-The `cozy/onlyoffice-dev` docker image can be used for local development on
-Linux (the `--net=host` option doesn't work on macOS). Just start it with:
+### Option 1: With Helper Script
+
+Use the helper script that works on both Linux and macOS:
+
+```bash
+./scripts/start-oo.sh
+```
+
+The script automatically:
+- Collects all instance hostnames from cozy-stack
+- Starts OnlyOffice with proper `--add-host` mappings
+- Waits for OnlyOffice to be ready
+
+### Option 2: Manual Docker Command
+
+**For macOS and Linux (port mapping):**
 
 ```bash
-$ docker run -it --rm --name=oodev --net=host cozy/onlyoffice-dev
+docker run -d --name onlyoffice-ds \
+    -p 8000:80 \
+    -e JWT_ENABLED=false \
+    -e ALLOW_PRIVATE_IP_ADDRESS=true \
+    -e ALLOW_META_IP_ADDRESS=true \
+    --add-host=cozy.localhost:host-gateway \
+    onlyoffice/documentserver:latest
 ```
 
-and run the stack with:
+**For Linux only (`--net=host`):**
 
 ```bash
-$ cozy-stack serve --disable-csp --onlyoffice-url=http://localhost:8000 --onlyoffice-inbox-secret=inbox_secret --onlyoffice-outbox-secret=outbox_secret
-$ cozy-stack features defaults '{"drive.office": {"enabled": true, "write": true}}'
+docker run -d --name onlyoffice-ds \
+    --net=host \
+    -e JWT_ENABLED=false \
+    -e ALLOW_PRIVATE_IP_ADDRESS=true \
+    -e ALLOW_META_IP_ADDRESS=true \
+    -e DS_PORT=8000 \
+    onlyoffice/documentserver:latest
+```
+
+### Configure cozy-stack
+
+Add to your `~/.cozy/cozy.yaml`:
+
+```yaml
+contexts:
+  default:
+    onlyoffice_url: http://localhost:8000/
+
+office:
+  default:
+    onlyoffice_url: http://localhost:8000/
+    onlyoffice_inbox_secret: ""
+    onlyoffice_outbox_secret: ""
 ```
 
-If you need to rebuild it, you can do that with:
+### Enable Feature Flag
 
 ```bash
-$ cd scripts/onlyoffice-dev
-$ docker build -t "cozy/onlyoffice-dev" .
+cozy-stack features defaults '{"drive.office": {"enabled": true, "write": true}}'
 ```
+
+### Troubleshooting
+
+**OnlyOffice can't download the document:**
+- Check OnlyOffice logs: `docker logs onlyoffice-ds`
+- Look for DNS errors like `ENOTFOUND cozy.localhost`
+- Ensure `--add-host` flag was applied: `docker exec onlyoffice-ds cat /etc/hosts | grep cozy`
+- Ensure `ALLOW_PRIVATE_IP_ADDRESS=true` is set
+
+**"Download failed" error in editor:**
+- The Document Server can't reach cozy-stack
+- Verify connectivity: `docker exec onlyoffice-ds wget -qO- http://cozy.localhost:8080/`
+
+**No "Open with OnlyOffice" option in Drive:**
+- Check feature flag: `cozy-stack features show`
+- Verify context has `onlyoffice_url`: check `/settings/context` endpoint

docs/office.md

@@ -31,6 +31,8 @@ Reference: https://api.onlyoffice.com/editors/save
 
 ## Routes
 
+> **Note:** For local development setup, see [Docker - OnlyOffice Document Server](docker.md#onlyoffice-document-server).
+
 ### GET /office/:id/open
 
 This route returns the parameters to open an office document. There are two

scripts/onlyoffice-dev/Dockerfile

@@ -0,0 +1,55 @@
+#!/bin/bash
+#
+# Start OnlyOffice Document Server for local development
+#
+# This script:
+# 1. Stops and removes any existing onlyoffice-ds container
+# 2. Collects all instance hostnames from cozy-stack
+# 3. Starts OnlyOffice with proper host mappings so it can reach cozy-stack
+#
+# Usage: ./scripts/start-oo.sh
+#
+# See docs/docker.md for more information
+
+set -e
+
+CONTAINER_NAME="onlyoffice-ds"
+PORT="${OO_PORT:-8000}"
+
+echo "Stopping existing OnlyOffice container..."
+docker stop $CONTAINER_NAME 2>/dev/null || true
+docker rm $CONTAINER_NAME 2>/dev/null || true
+
+echo "Collecting instance hostnames..."
+HOSTS=""
+for domain in $(go run . instances ls 2>/dev/null | awk '{print $1}' | sed 's/:8080//'); do
+  HOSTS="$HOSTS --add-host=$domain:host-gateway"
+done
+
+if [ -z "$HOSTS" ]; then
+  echo "Warning: No instances found. Adding default cozy.localhost"
+  HOSTS="--add-host=cozy.localhost:host-gateway"
+fi
+
+echo "Starting OnlyOffice Document Server on port $PORT..."
+docker run -d --name $CONTAINER_NAME \
+  -p $PORT:80 \
+  -e JWT_ENABLED=false \
+  -e ALLOW_PRIVATE_IP_ADDRESS=true \
+  -e ALLOW_META_IP_ADDRESS=true \
+  $HOSTS \
+  onlyoffice/documentserver:latest
+
+echo "Waiting for OnlyOffice to be ready..."
+for i in {1..60}; do
+  if curl -s http://localhost:$PORT/healthcheck 2>/dev/null | grep -q "true"; then
+    echo "OnlyOffice is ready at http://localhost:$PORT"
+    exit 0
+  fi
+  sleep 2
+  echo -n "."
+done
+
+echo ""
+echo "Warning: OnlyOffice did not become ready in time. Check logs with:"
+echo "  docker logs $CONTAINER_NAME"