Add Install Scripts: OpenCloud, OnlyOffice Document Server, Collabora Online by Robert-Janssen · Pull Request #177 · eshtek/hexos-docs

Robert-Janssen · 2026-02-28T14:38:49Z

Summary

Three new curated install scripts for deploying a complete OpenCloud document collaboration stack on HexOS/TrueNAS:

OpenCloud (community train, v4.0.3, chart v1.2.2) — Self-hosted cloud platform (oCIS fork) with file sync, sharing, and optional document collaboration via WOPI
OnlyOffice Document Server (community train, v9.3.0, chart v1.2.2) — Document editing server for OpenCloud/Nextcloud collaboration
Collabora Online (stable train, v25.04.9.2.1, chart v1.5.2) — Document editing server, alternative to OnlyOffice

Scripts

File	TrueNAS App Name	Train	Version
`opencloud.json`	opencloud	community	4.0.3
`onlyoffice.json`	onlyoffice-document-server	community	9.3.0
`collabora.json`	collabora	stable	25.04.9.2.1

Installation Questions

OpenCloud

Key	Type	Required	Default	Description
`app_url`	text	yes	—	HTTPS URL to access OpenCloud
`jwt_secret`	text	no	`$RANDOM_STRING(32)`	Shared JWT secret for internal auth and WOPI
`enable_collaboration`	boolean	no	`false`	Enable WOPI collaboration
`collaboration_type`	select	no	`collabora`	Collabora or OnlyOffice
`collaboration_url`	text	no	—	URL of collaboration server

OnlyOffice Document Server

Key	Type	Required	Default	Description
`jwt_secret`	text	no	`$RANDOM_STRING(32)`	Shared JWT secret for WOPI auth
`web_port`	number	no	`30134`	Web access port

Collabora Online

Key	Type	Required	Default	Description
`server_name`	text	yes	—	Hostname (host:port, no protocol)
`aliasgroup`	text	yes	—	Allowed connecting domains
`admin_user`	text	no	`admin`	Admin console username
`admin_password`	text	yes	—	Admin password (min 8 chars)
`web_port`	number	no	`9980`	Web access port

Key Design Decisions

JWT Secret Coordination (OpenCloud + OnlyOffice)

OpenCloud's TrueNAS chart maps both opencloud.jwt_secret and opencloud.collaboration.jwt_secret to environment variables that must be identical when using OnlyOffice collaboration. This script uses a single jwt_secret question that feeds both fields.

Both OpenCloud and OnlyOffice default to $RANDOM_STRING(32), allowing either app to be installed first. The user copies the generated JWT from whichever app was installed first into the other app's JWT field.

Collabora Uses WOPI Proof Keys (No JWT)

Collabora authenticates via WOPI Proof Keys rather than JWT. OpenCloud sets collaboration.proof_disable: true to bypass proof key validation in insecure/LAN setups. No shared secret is needed between OpenCloud and Collabora.

Storage Layout

OpenCloud: Three host-path directories under $LOCATION(ApplicationsPerformance)/opencloud/ — config, data, radicale_data. Runs as user/group 568, with apps:apps POSIX permissions.
OnlyOffice: PostgreSQL data at $LOCATION(ApplicationsPerformance)/onlyoffice/postgres_data with netdata:docker permissions (required by the chart).
Collabora: No persistent storage needed (stateless).

Resource Allocation

All three scripts request 2 CPUs and $MEMORY(10%, 4096) (10% of system RAM, minimum 4096 MB).

Collabora Password Validation

The TrueNAS Collabora chart enforces ^[a-zA-Z0-9!@#$%^&*?]{8,}$ on the admin password. The description instructs users to use a minimum of 8 characters with only letters, numbers, and !@#%^&*?.

Tested Configurations

OpenCloud + OnlyOffice collaboration: Verified working with shared JWT secret
OpenCloud standalone (collaboration disabled): Verified working
OnlyOffice standalone: Verified working
Collabora: Validated against chart schema; requires 8+ character admin password

Schema & Macros Used

Schema version: 3
Macros: $RANDOM_STRING(), $QUESTION(), $HOST_PATH(), $LOCATION(), $MEMORY()

Checklist

Scripts validated against live TrueNAS app schemas (truenas/apps repo)
JSON is valid and uses LF line endings
No https:// URLs in description strings (avoids HexOS editor parse issues)
No $ characters in description text (avoids macro parser conflicts)
Generic language in OnlyOffice/Collabora descriptions (not OpenCloud-specific)
All app_values fields match TrueNAS chart question variable names
Default ports match TrueNAS chart defaults

Updates documentation with troubleshooting guides and latest release note

Updates Emby and Jellyfin default ports. Ignore the updated script dates we can gen:all on the next push

Initial version of the OpenCloud installation script with collaboration support and various configuration options.

This JSON file contains the installation script details for OnlyOffice Document Server, including versioning, requirements, installation questions, and app values.

Added a JSON configuration script for Collabora Online installation, including versioning, requirements, installation questions, and application values.

Copilot

Pull request overview

Adds three curated HexOS/TrueNAS install scripts to deploy an OpenCloud-based document collaboration stack (OpenCloud + optional OnlyOffice or Collabora).

Changes:

Added opencloud.json curated install script with optional WOPI collaboration configuration.
Added onlyoffice.json curated install script with JWT coordination and Postgres host-path storage.
Added collabora.json curated install script with admin/WebUI and allowed-domain configuration.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
docs/public/install-scripts/opencloud.json	New install script for deploying OpenCloud with optional WOPI collaboration settings.
docs/public/install-scripts/onlyoffice.json	New install script for deploying OnlyOffice Document Server with configurable web port and persistent Postgres data.
docs/public/install-scripts/collabora.json	New install script for deploying Collabora Online with WebUI credentials and allowed-domain configuration.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/public/install-scripts/onlyoffice.json

Copilot · 2026-02-28T14:43:27Z

docs/public/install-scripts/onlyoffice.json

+        "ports": [
+            30134
+        ]


requirements.ports is hardcoded to 30134, but the script allows users to change the port via the web_port question. This can make port-availability checks inaccurate; consider leaving requirements.ports empty here (or otherwise ensure it reflects the chosen port).

Suggested change

"ports": [

30134

]

"ports": []

@copilot Maybe the port should just remain hardcoded? Other scripts like nextcloud also don't allow the user to specify the port.

Copilot · 2026-02-28T14:43:27Z

docs/public/install-scripts/onlyoffice.json

+        {
+            "path": "$LOCATION(ApplicationsPerformance)/onlyoffice/postgres_data",
+            "username": "netdata",
+            "access": "write",
+            "posix": {
+                "groupname": "docker"
+            }
+        }


ensure_permissions_exists grants netdata write access to the Postgres data directory. In other curated scripts using netdata:docker for postgres_data, access is typically read (e.g., nextcloud.json, home-assistant.json, immich.json). Unless OnlyOffice specifically requires write here, consider switching to read to avoid over-broad permissions.

docs/public/install-scripts/collabora.json

Copilot · 2026-02-28T14:43:28Z

docs/public/install-scripts/collabora.json

+        ],
+        "permissions": [],
+        "ports": [
+            9980


requirements.ports is hardcoded to 9980, but the script allows users to change the port via the web_port question. This can make port-availability checks inaccurate; consider leaving requirements.ports empty here (or otherwise ensure it reflects the chosen port).

Suggested change

9980

@copilot Here too, maybe the port should just remain hardcoded? Other scripts like nextcloud also don't allow the user to specify the port.

Copilot · 2026-02-28T14:43:28Z

docs/public/install-scripts/collabora.json

+        {
+            "question": "Allowed Domains",
+            "description": "Comma-separated list of domains allowed to connect (e.g., cloud.example.com). These should be the domains of your cloud platform.",
+            "type": "text",
+            "key": "aliasgroup",
+            "required": true
+        },


The question says this is a “comma-separated list of domains”, but $QUESTION(aliasgroup) is passed as a single string inside aliasgroup1 (an array). Unless the underlying chart splits on commas, a value like a.com,b.com will be treated as one entry; either update the description to match what’s actually supported, or collect multiple entries and map them to multiple array items.

Copilot · 2026-02-28T14:43:28Z

docs/public/install-scripts/opencloud.json

+            "question": "Application URL",
+            "description": "The full HTTPS URL to access OpenCloud (e.g., cloud.example.com).",
+            "type": "text",


The description says “full HTTPS URL”, but the example omits the scheme (cloud.example.com). To avoid user confusion (and misconfiguration if the underlying app expects a full URL), align the wording and example (either require a full URL, or explicitly say “hostname (no protocol)”).

Copilot · 2026-02-28T14:43:28Z

docs/public/install-scripts/opencloud.json

+            "question": "Collaboration Server URL",
+            "description": "The HTTPS URL of your Collabora or OnlyOffice server (e.g., office.example.com). Only required if collaboration is enabled.",
+            "type": "text",
+            "key": "collaboration_url",
+            "default": "",
+            "required": false


The description says “HTTPS URL” but the example omits the scheme (office.example.com). Align the wording/example so users know whether they should enter a full URL (with scheme) or just a hostname.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

jerodfritz and others added 5 commits January 21, 2026 12:28

Merge pull request eshtek#153 from eshtek/dev

1203383

Updates documentation with troubleshooting guides and latest release note

Merge pull request eshtek#156 from eshtek/dev

63913c4

Updates Emby and Jellyfin default ports. Ignore the updated script dates we can gen:all on the next push

Add initial OpenCloud installation script

f84a0ff

Initial version of the OpenCloud installation script with collaboration support and various configuration options.

Add installation script for OnlyOffice Document Server

fab70c7

This JSON file contains the installation script details for OnlyOffice Document Server, including versioning, requirements, installation questions, and app values.

Add Collabora installation script configuration

22c7163

Added a JSON configuration script for Collabora Online installation, including versioning, requirements, installation questions, and application values.

Copilot AI review requested due to automatic review settings February 28, 2026 14:38

Copilot started reviewing on behalf of Robert-Janssen February 28, 2026 14:39 View session

Copilot AI reviewed Feb 28, 2026

View reviewed changes

Robert-Janssen and others added 2 commits February 28, 2026 16:07

Update docs/public/install-scripts/onlyoffice.json

f50ce9e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/public/install-scripts/collabora.json

15e2874

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Install Scripts: OpenCloud, OnlyOffice Document Server, Collabora Online#177

Add Install Scripts: OpenCloud, OnlyOffice Document Server, Collabora Online#177
Robert-Janssen wants to merge 7 commits intoeshtek:devfrom
Robert-Janssen:patch-1

Robert-Janssen commented Feb 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Robert-Janssen Feb 28, 2026

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Robert-Janssen Feb 28, 2026

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Robert-Janssen commented Feb 28, 2026

Summary

Scripts

Installation Questions

OpenCloud

OnlyOffice Document Server

Collabora Online

Key Design Decisions

JWT Secret Coordination (OpenCloud + OnlyOffice)

Collabora Uses WOPI Proof Keys (No JWT)

Storage Layout

Resource Allocation

Collabora Password Validation

Tested Configurations

Schema & Macros Used

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Robert-Janssen Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Robert-Janssen Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants