docs: refine Nextcloud Office configuration and installation pages

chrip · juliusknorr · commit 1ba014de7a24 · 2026-06-17T14:07:28.000+02:00
- Rewrite configuration page to match actual settings.php UI structure
  exactly: server settings, common settings, editor customization,
  common templates, security/watermarks — with correct field labels
- Add Docker Compose example for internal URL configuration
- Fix verify_peer_off config.php value (must be string "true", not bool)
- Add eurooffice:documentserver occ command (without --check prints URL)
- Fix installation overview: remove H2 sections so sub-pages appear
  correctly in sidebar navigation
- Fix heading overline length on euro-office/index.rst

Assisted-by: claude-code:claude-sonnet-4-6
Signed-off-by: Christoph Schaefer &lt;christoph.schaefer@nextcloud.com&gt;
diff --git a/admin_manual/office/euro-office/configuration.rst b/admin_manual/office/euro-office/configuration.rst
@@ -20,113 +20,193 @@ Alternatively, install the app using the :command:`occ` command:
 
     php occ app:install eurooffice
 
-Connecting to the Document Server
------------------------------------
+Server settings
+---------------
 
-1. Open :menuselection:`Settings --> Administration --> Euro-Office`.
-2. Enter the Document Server URL in the **Euro-Office Docs address** field:
+Open :menuselection:`Settings --> Administration --> Euro-Office` to configure the connection.
 
-   .. code-block:: text
+**Nextcloud Office address**
+    The URL of the Euro-Office Document Server, accessible from both the Nextcloud server
+    and end-user browsers:
 
-       https://<documentserver>/
+    .. code-block:: text
 
-   where ``<documentserver>`` is the hostname or IP of the machine running Euro-Office Document Server.
+        https://<documentserver>/
 
-3. Enter the **Secret key** — this must match the JWT secret configured on the Document Server:
+**Disable certificate verification (insecure)**
+    Disables TLS certificate checks. Only enable this in test environments.
 
-   - **deb/rpm install:** the secret is in ``/etc/euro-office/documentserver/local.json``
-     under ``services.CoAuthoring.secret.browser.string``.
-   - **Docker install:** the value of the ``JWT_SECRET`` environment variable used when
-     starting the container.
+**Secret key (leave blank to disable)**
+    The JWT shared secret. Must match the value configured on the Document Server:
 
-4. Click **Save**.
+    - **deb/rpm install:** ``/etc/euro-office/documentserver/local.json`` →
+      ``services.CoAuthoring.secret.browser.string``
+    - **Docker install:** the ``JWT_SECRET`` environment variable
 
-A green status indicator confirms a successful connection.
+Click **Save** to apply. A green status indicator confirms a successful connection.
 
 Advanced server settings
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Expand **Advanced server settings** when the public Document Server URL is not directly
+reachable from your Nextcloud host (for example, behind a NAT or split-horizon DNS):
+
+**Authorization header (leave blank to use default header)**
+    The HTTP header used to carry the JWT token. Defaults to ``Authorization``.
+
+**Nextcloud Office address for internal requests from the server**
+    The URL Nextcloud uses to contact the Document Server directly (server-to-server).
+    Must be reachable from the Nextcloud host.
 
-If the public Document Server URL is not reachable from your Nextcloud server (for example,
-behind a NAT or a split-horizon DNS), configure separate addresses for server-side and
-client-side communication:
+**Server address for internal requests from Nextcloud Office**
+    The URL the Document Server uses to send callbacks back to Nextcloud. Must be
+    reachable from the Document Server host.
 
-- **Euro-Office Docs address for internal requests from the server** — the URL Nextcloud uses
-  to contact the Document Server directly (must be reachable from the Nextcloud host).
-- **Nextcloud address available from Document Server** — the URL the Document Server uses
-  to send callbacks back to Nextcloud (must be reachable from the Document Server host).
+.. tip::
+    **Docker Compose example**
+
+    When Nextcloud and Euro-Office run as services in the same Docker Compose network,
+    containers can reach each other by service name. Given a ``compose.yml`` with services
+    named ``nextcloud`` and ``eurooffice``:
+
+    - **Nextcloud Office address** (public): ``https://office.example.com/``
+    - **Nextcloud Office address for internal requests from the server**: ``http://eurooffice/``
+    - **Server address for internal requests from Nextcloud Office**: ``http://nextcloud/``
+
+    The public address is used by end-user browsers. The internal addresses bypass the
+    public reverse proxy and let the two containers communicate directly over the
+    shared Docker network.
 
 Common settings
 ---------------
 
+These settings become available after a successful server connection.
+
 .. list-table::
     :header-rows: 1
-    :widths: 35 65
+    :widths: 50 50
 
     * - Setting
       - Description
+    * - Allow the following groups to access the editors
+      - Restricts editor access to specified Nextcloud groups.
+    * - Use Nextcloud Office to generate a document preview
+      - Generates thumbnail previews for Office files. Takes up additional disk space.
     * - Open file in the same tab
       - Opens documents inside Nextcloud instead of a new browser tab.
     * - Enable sharing
-      - Allows users to share files directly from within the editor.
-    * - Generate document preview
-      - Uses Euro-Office to generate thumbnail previews for Office files.
-    * - Advanced document permissions
+      - Allows users to share files from within the editor. May increase editor load time.
+    * - Provide advanced document permissions
       - Enables per-user fine-grained permissions (review-only, comment-only, etc.)
-        on shared files.
+        on shared files via the sharing dialog.
+    * - Keep metadata for each version once the document is edited
+      - Stores version metadata each time a document is saved. Takes up additional disk space.
+    * - Enable background connection check to the editors
+      - Runs a periodic cron job to verify the Document Server is reachable.
     * - Enable e-mail notifications
-      - Sends e-mail notifications when a document is commented or edited.
-    * - Keep version history
-      - Stores metadata for each version created while editing.
-    * - Document protection
-      - Sets who can protect/unprotect documents: document owners only (``owner``)
-        or all editors (``all``).
-    * - Restrict access to groups
-      - Limits editor access to specific Nextcloud groups.
-
-Customization settings
------------------------
+      - Sends e-mail notifications on comments and edits.
+    * - Unknown author display name
+      - Display name shown for edits made by users not known to Nextcloud.
+
+**Default application for opening the format**
+    Checkboxes for each supported file format. When enabled for a format, Nextcloud
+    Office becomes the default handler when that file type is clicked.
+
+**Open the file for editing**
+    Checkboxes for formats that can be edited natively. Enabling a format allows users
+    to edit it directly. Note that saving back to some formats may result in data loss
+    due to format restrictions.
+
+Editor customization settings
+------------------------------
 
 .. list-table::
     :header-rows: 1
-    :widths: 35 65
+    :widths: 50 50
 
     * - Setting
       - Description
+    * - Keep intermediate versions when editing (forcesave)
+      - Saves an intermediate version each time a user explicitly saves, in addition
+        to the final version saved when the editor closes.
+    * - Enable live-viewing mode when accessing file by public link
+      - Shows live updates to external viewers accessing a file via a public link.
     * - Display Chat menu button
       - Shows or hides the in-editor chat panel.
-    * - Compact header
-      - Displays a more compact toolbar header in the editor.
-    * - Display Feedback & Support button
+    * - Display the header more compact
+      - Displays a more compact toolbar header.
+    * - Display Feedback & Support menu button
       - Shows or hides the Feedback & Support entry in the editor menu.
-    * - Forcesave
-      - Saves an intermediate version of the document each time a user explicitly
-        saves (in addition to the final version saved on editor close).
     * - Display Help menu button
       - Shows or hides the Help entry in the editor menu.
-    * - Review display mode
-      - Default mode for viewing tracked changes: ``original``, ``markup``, or ``final``.
-    * - Editor theme
-      - Default color theme for the editor interface.
-    * - Run document macros
-      - Allows macros embedded in documents to execute.
-    * - Enable plugins
-      - Allows third-party plugins inside the editor.
-
-Watermark settings
-------------------
 
-Watermarks are overlaid on documents when they are opened by specified users or via shares.
+**REVIEW mode for viewing**
+    Default mode for displaying tracked changes: **Markup**, **Final**, or **Original**.
+
+**Default editor theme**
+    Color theme for the editor interface: **Same as system**, **Light**, or **Dark**.
+
+Common templates
+----------------
+
+Administrators can upload shared document templates that are available to all users
+when creating new files. Templates are managed in the **Common templates** section of
+the admin settings page.
+
+Security
+--------
 
-Enable watermarking under :menuselection:`Settings --> Administration --> Euro-Office --> Security`.
+**Enable plugins**
+    Allows third-party plugins to run inside the editor.
 
-The watermark text supports the following placeholders:
+**Run document macros**
+    Allows macros embedded in documents to execute.
+
+**Enable document protection for**
+    Controls who can protect or unprotect documents:
+
+    - **All users** — any editor can protect or unprotect the document.
+    - **Owner only** — only the file owner can change protection.
+
+Watermarks
+^^^^^^^^^^
+
+Watermarks are overlaid on documents when they are opened by specified users or via shares.
+Enable **Enable watermarking** to configure the watermark.
+
+**Watermark text** — the text overlaid on the document. Supported placeholders:
 
 - ``{userId}`` — Nextcloud user ID
 - ``{userDisplayName}`` — user's display name
 - ``{email}`` — user's e-mail address
 - ``{date}`` — current date
 - ``{themingName}`` — Nextcloud instance name from theming settings
 
+Watermark visibility can be configured per audience:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 50 50
+
+    * - Option
+      - When the watermark is shown
+    * - Show watermark on tagged files
+      - Files with specific system tags (requires the System Tags app).
+    * - Show watermark for users of groups
+      - Users belonging to selected groups.
+    * - Show watermark for all shares
+      - Any user who accesses the file via a share.
+    * - Show watermark for read only shares
+      - Users with read-only share access.
+    * - Show watermark for all link shares
+      - Anyone accessing the file via a public link.
+    * - Show watermark for download hidden shares
+      - Public links where file download is disabled.
+    * - Show watermark for read only link shares
+      - Public links with read-only access.
+    * - Show watermark on link shares with specific system tags
+      - Public links on files with specific system tags.
+
 occ commands
 ------------
 
@@ -140,6 +220,14 @@ Settings can also be managed via :command:`occ`:
     # Write a setting
     php occ config:app:set eurooffice DocumentServerUrl --value="https://office.example.com/"
 
+The ``eurooffice:documentserver`` command shows the configured server URL and optionally
+tests the connection:
+
+.. code-block:: bash
+
+    # Print the currently configured Document Server URL
+    php occ eurooffice:documentserver
+
     # Check the connection to the Document Server
     php occ eurooffice:documentserver --check
 
@@ -153,8 +241,12 @@ Settings can also be set directly in ``config/config.php`` under the ``eurooffic
     "eurooffice" => [
         "DocumentServerUrl" => "https://office.example.com/",
         "jwt_secret" => "your-secret",
-        "verify_peer_off" => false,
+        "verify_peer_off" => "true",
     ],
 
-Settings defined in ``config.php`` are used as fallback when no value is set via the admin UI
-or :command:`occ`. The UI takes precedence.
+.. note::
+    ``verify_peer_off`` is read as a string — use ``"true"`` to disable certificate
+    verification, not a PHP boolean.
+
+Settings defined in ``config.php`` are used as fallback when no value is set via the
+admin UI or :command:`occ`. The UI takes precedence.
diff --git a/admin_manual/office/euro-office/index.rst b/admin_manual/office/euro-office/index.rst
@@ -1,6 +1,6 @@
-===============
+================
 Nextcloud Office
-===============
+================
 
 Nextcloud Office is Nextcloud's built-in office solution, powered by Euro-Office Document Server.
 It enables real-time collaborative editing of text documents, spreadsheets, and presentations
diff --git a/admin_manual/office/euro-office/installation.rst b/admin_manual/office/euro-office/installation.rst
@@ -2,51 +2,39 @@
 Installation
 ============
 
-Nextcloud Office requires a running Euro-Office Document Server that Nextcloud can reach over the network.
-The Document Server is packaged separately and must be installed before connecting Nextcloud to it.
-
-Supported platforms
--------------------
+Nextcloud Office requires a running Euro-Office Document Server that Nextcloud can reach
+over the network. Choose the installation method that fits your infrastructure:
 
 .. list-table::
     :header-rows: 1
-    :widths: 30 20 20
+    :widths: 40 20 40
 
     * - Distribution
       - Architectures
       - Method
     * - Ubuntu 24.04 LTS (Noble)
       - amd64, arm64
-      - .deb package
+      - :doc:`installation_ubuntu`
     * - Debian 12 (Bookworm)
       - amd64, arm64
-      - .deb package
+      - :doc:`installation_debian`
     * - Any Linux host
       - amd64, arm64
-      - Docker
+      - :doc:`installation_docker`
+
+**Minimum system requirements:**
 
-Installation methods
---------------------
+- 4 GB RAM (8 GB recommended for multi-user deployments)
+- 10 GB disk space
+- The Document Server and Nextcloud must be able to reach each other over HTTPS in production
 
-- :doc:`installation_ubuntu`
-- :doc:`installation_debian`
-- :doc:`installation_docker`
+.. note::
+    The Document Server does not need to run on the same host as Nextcloud.
+    A reverse proxy (nginx or Apache) in front of the Document Server is required for
+    production deployments to expose it over HTTPS.
 
 .. toctree::
-    :hidden:
 
     installation_ubuntu
     installation_debian
     installation_docker
-
-System requirements
--------------------
-
-- 4 GB RAM minimum (8 GB recommended for multi-user deployments)
-- 10 GB disk space minimum
-- The Document Server and Nextcloud must be able to reach each other over HTTPS in production
-
-.. note::
-    The Document Server does not need to run on the same host as Nextcloud.
-    A reverse proxy (nginx or Apache) in front of the Document Server is required for production
-    deployments so that the server is reachable over HTTPS.
