Overview

The validated baseline is the openSUSE-based grommunio appliance 2026.06.1. The examples consistently use the neutral appliance domain https://mail.example.test; paths such as /web/, /admin/, /auth/, /chat/, /meet/ and /files/ live on the same appliance.This article shows how to bring grommunio Files and Office into operation from the grommunio appliance and validate real file and office workflows.

It covers installation, storage, user access, upload, download, sharing, online office, simultaneous editing, web integration, logs and acceptance.

Tested environment

  • grommunio 2026 on the openSUSE-based grommunio appliance.

  • All appliance commands are run directly on the grommunio appliance.

  • Public examples consistently use the neutral appliance domain https://mail.example.test.

1. Starting point & prerequisites

The starting point is a grommunio installation with working DNS, TLS, admin access and a clean baseline validation. Each article covers exactly the building block required for a complete collaboration platform.

2. Step-by-step guide

This guide shows how to install, configure and validate grommunio Files and grommunio Office on an existing grommunio 2026.06.1 appliance. At the end, users should be able to upload files, share them and open DOCX, XLSX and PPTX directly in the browser.

  • You install grommunio Files 32.0.12 and grommunio Office 9.4.0 from the grommunio repository.

  • You configure databases, storage, Redis/file locking, cron and reverse proxy.

  • You connect Files with Office and validate the real editor workflow.

  • You enable the Files/Office integration in grommunio Web.

  • You test upload, download, sharing, a second user, saving and reopening.

  • You document operations, backup and troubleshooting points for production.

The series is intended to be chronological:install grommunio 2026,antispam with Rspamd,SSO with Keycloak,Meet,Chatand now Files with Office. Product context is available on thegrommunio product page.

Architecture: Files, Office, Web and Auth

grommunio Files provides file storage, WebDAV, shares and the user interface. The package metadata on the validated appliance identifies Nextcloud as the technical basis. grommunio Office adds browser-based editing and is connected through the OnlyOffice app in Files. grommunio Web can expose Files as an integrated entry point; in this series, identity comes from grommunio-auth and Keycloak.

  • grommunio-auth / Keycloak
  • grommunio Web
  • entry point to grommunio Files
  • WebDAV, shares, user files
  • OnlyOffice app
  • grommunio Office Document Service
  • save back to Files

Prerequisites

  • A working grommunio 2026.06.1 appliance with Web, Admin, mail and a valid FQDN.

  • HTTPS must be reachable through the production FQDN. Self-signed certificates are only appropriate for isolated labs.

  • Enough storage for user data, versions, trash, database and backups.

  • MariaDB, nginx, PHP-FPM, Redis and systemd must be healthy.

  • Users need WebDAV/Files privileges. In validation, `privWeb`, `privDav` and `privFiles` were relevant.

  • Create a snapshot or appliance backup before making changes.

Step 1: Check the baseline

Do not start with installation. Start with a short baseline check so you can later tell whether Files/Office introduced a new issue or whether it was present before.

bash
cat /etc/os-release
hostname -f
ip addr
df -h
free -h
systemctl --failed
rpm -qa | grep -i grommunio | sort
ss -lntup

Step 2: Identify packages and roles

On the validated grommunio 2026.06.1 appliance, Files and Office came as native packages from the grommunio repository. Files provided Nextcloud-based file storage; Office provided the document service and RabbitMQ as a service dependency.

bash
zypper search -s grommunio-files grommunio-office
zypper info grommunio-files grommunio-office grommunio-office-fonts
rpm -ql grommunio-setup | grep -E 'files|office'

Validated versions:

  • grommunio-files: 32.0.12-lp160.5.1
  • grommunio-office: 9.4.0-lp160.6.1
  • rabbitmq-server: 4.1.5
  • grommunio-web: 3.19.371.ge256c4858

Step 3: Install Files and Office

Install Files, Office and RabbitMQ together. This keeps PHP dependencies, Office services, fonts and the Files application at a consistent package level.

bash
zypper --non-interactive install --auto-agree-with-licenses \
 grommunio-files \
 grommunio-office \
 rabbitmq-server

Afterwards verify that the packages are really installed. If `zypper info` showed “not installed” before, `rpm -q` must now return concrete versions.

bash
rpm -q grommunio-files grommunio-office rabbitmq-server

Step 4: Create databases and Files configuration

Files needs its own database and a configuration readable by the service context. Secrets do not belong in screenshots, tickets or blog posts. Use secret management or at least root-readable files.

bash
install -d -m 0750 /root/grommunio-secrets
openssl rand -base64 32 >/root/grommunio-secrets/files-db-password
chmod 0600 /root/grommunio-secrets/files-db-password


FILES_DB_PASSWORD="$(cat /root/grommunio-secrets/files-db-password)"
mariadb <<SQL
CREATE DATABASE IF NOT EXISTS grofiles CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER IF NOT EXISTS 'grofiles'@'localhost' IDENTIFIED BY '${FILES_DB_PASSWORD}';
GRANT ALL PRIVILEGES ON grofiles.* TO 'grofiles'@'localhost';
FLUSH PRIVILEGES;
SQL

The appliance provides the relevant paths. In the validated installation, application, configuration, external apps, data and logs were placed in these locations.

  • /usr/share/grommunio-files
  • /usr/share/grommunio-files/config/config.php
  • /var/lib/grommunio-files/data
  • /var/lib/grommunio-files/apps-external
  • /var/log/grommunio-files/files.log

Step 5: Install Files and set trusted domains

Run the Files initialization with the real FQDN. In production this is your mail/groupware FQDN without a lab port. `overwritewebroot` remains `/files` because Files is published behind nginx under that path.

bash
cd /usr/share/grommunio-files


sudo -u grofiles./occ maintenance:install \
 --database mysql \
 --database-name grofiles \
 --database-user grofiles \
 --database-pass "$FILES_DB_PASSWORD" \
 --admin-user grofiles-admin \
 --admin-pass '<secure-admin-password>' \
 --data-dir /var/lib/grommunio-files/data


MAIL_FQDN="mail.example.test"


sudo -u grofiles./occ config:system:set trusted_domains 0 --value="${MAIL_FQDN}"
sudo -u grofiles./occ config:system:set overwrite.cli.url --value="https://${MAIL_FQDN}/files"
sudo -u grofiles./occ config:system:set overwritewebroot --value="/files"
sudo -u grofiles./occ config:system:set overwriteprotocol --value="https"
sudo -u grofiles./occ config:system:set default_phone_region --value="AT"

Step 6: Enable Redis, file locking and cron

File locking and background jobs are not optional decoration. Without healthy jobs, previews, cleanup, versions and some app actions will eventually lag behind.

bash
sudo -u grofiles./occ config:system:set memcache.local --value="\\OC\\Memcache\\APCu"
sudo -u grofiles./occ config:system:set memcache.locking --value="\\OC\\Memcache\\Redis"
sudo -u grofiles./occ config:system:set redis host --value="127.0.0.1"
sudo -u grofiles./occ config:system:set redis port --value="6379" --type=integer
sudo -u grofiles./occ background:cron
systemctl enable --now grommunio-files-cron.timer

Step 7: Connect the user source

The validated appliance used `user_external` so grommunio users can authenticate against the existing DAV/groupware access. This avoids inventing a second standalone user store in Files.

bash
cd /usr/share/grommunio-files
sudo -u grofiles./occ app:enable user_external
sudo -u grofiles./occ config:system:set user_backends 0 class --value="\\OCA\\UserExternal\\BasicAuth"
sudo -u grofiles./occ config:system:set user_backends 0 arguments 0 --value="https://${MAIL_FQDN} -f)/dav"

Then verify in grommunio Admin that users have the required privileges. In validation, two normal users with Web, DAV and Files privileges were sufficient.

bash
grommunio-admin user query username privWeb privDav privFiles --format json-flat

Step 8: Prepare Office database and services

grommunio Office needs its own database and several services. RabbitMQ, `ds-docservice` and `ds-converter` must be running; otherwise Files may load while the editor stays empty or reports download/callback errors.

bash
openssl rand -base64 32 >/root/grommunio-secrets/office-db-password
chmod 0600 /root/grommunio-secrets/office-db-password
OFFICE_DB_PASSWORD="$(cat /root/grommunio-secrets/office-db-password)"


mariadb <<SQL
CREATE DATABASE IF NOT EXISTS groffice CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER IF NOT EXISTS 'groffice'@'localhost' IDENTIFIED BY '${OFFICE_DB_PASSWORD}';
GRANT ALL PRIVILEGES ON groffice.* TO 'groffice'@'localhost';
FLUSH PRIVILEGES;
SQL


mysql groffice < /usr/libexec/grommunio-office/server/schema/mysql/createdb.sql
systemctl enable --now rabbitmq-server ds-docservice ds-converter
systemctl start ds-themegen ds-fontgen || true

Step 9: Connect Files with Office

Enable the OnlyOffice app in Files and set the URLs to match the nginx publishing paths. In the validated environment, Files was reachable under `/files/` and Office under `/office/`.

bash
cd /usr/share/grommunio-files
sudo -u grofiles./occ app:enable onlyoffice
sudo -u grofiles./occ config:app:set onlyoffice DocumentServerUrl --value="https://${MAIL_FQDN} -f)/office/"
sudo -u grofiles./occ config:app:set onlyoffice DocumentServerInternalUrl --value="https://${MAIL_FQDN} -f)/office/"
sudo -u grofiles./occ config:app:set onlyoffice StorageUrl --value="https://${MAIL_FQDN}/files/"
sudo -u grofiles./occ config:app:set onlyoffice customizationForcesave --value=true
sudo -u grofiles./occ config:app:set onlyoffice sameTab --value=true

In production, TLS must validate cleanly. In an isolated self-signed lab, disabling peer verification may be required for the test. This is a lab workaround, not a production standard.

bash
# Nur für isolierte Self-Signed-Labs:
sudo -u grofiles./occ config:app:set onlyoffice verify_peer_off --value=true


# Für produktive Systeme:
sudo -u grofiles./occ config:app:delete onlyoffice verify_peer_off || true

Step 10: Integrate grommunio Web

Enable the Files and Office functions in the grommunio Web plugin. Users should be able to move from Web into Files and edit Office file types directly.

bash
grep -E 'PLUGIN_FILES_USER_DEFAULT_ENABLE|PLUGIN_FILES_ONLYOFFICE_ENABLE|PLUGIN_FILES_ONLYOFFICE_FILETYPES' \
 /etc/grommunio-web/config-files.php


# Erwartung:
# define('PLUGIN_FILES_USER_DEFAULT_ENABLE', true);
# define('PLUGIN_FILES_ONLYOFFICE_ENABLE', true);
# define('PLUGIN_FILES_ONLYOFFICE_FILETYPES', ".doc,.docx,.docxf,.oform,.odp,.ods,.odt,.ppt,.pptx,.xls,.xlsx");

If you need to change these values, edit `/etc/grommunio-web/config-files.php` and restart the affected services. Use the real FQDN of the environment, not arbitrary example URLs.

bash
systemctl restart nginx php-fpm grommunio-web || true

From grommunio-auth through Web to Files and Office

grommunio-auth is the central identity component of the appliance. This article only covers the Files/Office path: create the `grommunio-files` Keycloak client, enable `user_oidc` in Files, apply the grommunio-auth Files adapter and test the browser flow through the real `/files` path.

Validated Files path:

  • Keycloak realm: grommunio
  • Keycloak client: grommunio-files
  • Files app: user_oidc
  • Adapter script: /usr/share/grommunio-auth/adaptor-config-scripts/setup-gk-app-g-files
  • Browser test: https://mail.example.test/files/

The entry into grommunio Web through grommunio-auth and Keycloak was checked. The login page and MFA step are visible. In this Files/Office validation, the DAV-based Files access was also active; therefore the article documents the tested DAV fallback and shows where the central OIDC integration for Files is attached.

https://mail.example.test/web/

Screenshot: The grommunio-auth login page is the central entry point for grommunio Web. Check the real FQDN, certificate and realm here before troubleshooting Files or Office.

https://mail.example.test/auth/

Screenshot: The MFA setup is shown as a full page; QR code and secret are deliberately hidden. In production, recovery codes, tokens and TOTP secrets must never appear in screenshots or operations documents.

For Files there are two clean operating paths. The quickly testable fallback uses `user_external` against grommunio DAV access. The SSO path uses the installed `user_oidc` app and the `setup-gk-app-g-files` adapter script. For that, Files needs its own confidential OIDC client in the same Keycloak realm as grommunio Web.

Important plugin clarification: on the validated 2026.06.1 appliance, `oauth2`, `onlyoffice`, `user_external` and `user_oidc` were present. A `user_saml` plugin was not the required Files path there. If an enterprise IdP speaks SAML, integrate it cleanly at the Keycloak/grommunio-auth layer; in this guide, Files receives the Keycloak provider through OIDC.

bash
cd /usr/share/grommunio-files
sudo -u grofiles./occ app:list | grep -E 'user_oidc|user_saml|saml|oauth2|user_external|onlyoffice'

Create the client if it is missing: `Create client`, client type `OpenID Connect`, client ID `grommunio-files`. Afterwards keep `Client authentication` and `Standard flow` enabled. `Direct access grants`, `Implicit flow` and `Service account roles` stay disabled.

https://mail.example.test/auth/admin/

Screenshot: The Files client is a confidential OIDC client with standard flow enabled.

The redirect URIs must match the installed `user_oidc` app. On the validated appliance both variants were useful because grommunio Files can return with or without `index.php`, depending on routing.

  • Valid redirect URIs:
  • https://mail.example.test/files/index.php/apps/user_oidc/code
  • https://mail.example.test/files/apps/user_oidc/code
  • Web origins:
  • https://mail.example.test
https://mail.example.test/auth/admin/

Screenshot: The Files callback URIs point to the real `user_oidc` route below `/files`.

bash
cd /usr/share/grommunio-files
sudo -u grofiles./occ app:enable user_oidc


# The adapter reads the file generated by grommunio-auth:
# /var/cache/grommunio-auth/adaptor-config/keycloak-grommunio-files.json
/usr/share/grommunio-auth/adaptor-config-scripts/setup-gk-app-g-files


# Then verify without printing secrets:
sudo -u grofiles./occ user_oidc:providers --output=json_pretty

Important for the browser flow: grommunio Files must be able to fetch the Keycloak discovery document server-side. In production, use a publicly or internally trusted TLS certificate. In an isolated lab with a self-signed certificate, updating only the system trust store is not always enough; grommunio Files/Nextcloud also uses its own bundle at `/usr/share/grommunio-files/resources/config/ca-bundle.crt`. Only when this request works without certificate errors should you consider the Files SSO start technically validated.

bash
curl -fsS https://mail.example.test/auth/realms/grommunio/.well-known/openid-configuration >/dev/null


# Only in an isolated lab with a self-signed certificate:
cat /etc/pki/trust/anchors/mail-example-test.pem >> /usr/share/grommunio-files/resources/config/ca-bundle.crt
systemctl restart php-fpm nginx


# Afterwards the SSO start must redirect to Keycloak:
curl -kI https://mail.example.test/files/index.php/apps/user_oidc/login/1
https://mail.example.test/files/

Screenshot: After adapter configuration, grommunio Files shows the Keycloak entry in addition to direct Files login.

Redirect URIs must always match the real FQDN and the real Files application path. For Files, the callback route of the installed `user_oidc` app is authoritative, not an invented URL.

https://mail.example.test/files/

Screenshot: The DAV fallback ends at the Files login. If Files should run fully through Keycloak, the `user_oidc` provider must then be configured and tested as its own browser flow.

grommunio Web

Authentication
grommunio-auth / Keycloak
User source
grommunio users
Separate browser session
yes

grommunio Files

Authentication
user_oidc through Keycloak or DAV fallback
User source
Keycloak/grommunio DAV
Separate browser session
configuration dependent

grommunio Office

Authentication
Office callback through Files app
User source
Files document context
Separate browser session
editor session in browser

Step 11: Run health checks

First check services and HTTP routes. `Office /healthcheck` must return `true`. Files redirects to login without a session, which is expected.

bash
systemctl --no-pager --plain is-active nginx mariadb rabbitmq-server ds-docservice ds-converter grommunio-files-cron.timer php-fpm
systemctl --failed --no-pager --plain
ss -lntup | grep -E ':(80|443|8000|3306|6379)'
curl -kIs https://${MAIL_FQDN}/files/ | head -5
curl -ks https://${MAIL_FQDN} -f)/office/healthcheck
bash
Validated result:
- Files returns HTTP 302 to login without a session.
- Office /healthcheck returns true.
- ds-docservice listens locally on port 8000.
- nginx, MariaDB, RabbitMQ, ds-docservice, ds-converter, php-fpm and Files cron are active.
- systemctl --failed reports 0 failed units.

Step 12: Validate login and files

Open Files with a normal grommunio user. If you sign in directly to Files, the validated path uses BasicAuth against the existing grommunio user source. In a fully seamless SSO architecture, also validate the entry point from grommunio Web.

https://mail.example.test/files/

Screenshot: Login to grommunio Files with a normal user.

Then upload one DOCX, one XLSX and one PPTX file. This validates not only the Files UI, but also the Office mapping for each file type.

bash
curl -k -u 'alice@example.test:<password>' -T ForgeOne-Files-Office-Test.docx \
 https://mail.example.test/files/remote.php/dav/files/alice@example.test/ForgeOne-Files-Office-Test.docx


curl -k -u 'alice@example.test:<password>' -T ForgeOne-Files-Office-Test.xlsx \
 https://mail.example.test/files/remote.php/dav/files/alice@example.test/ForgeOne-Files-Office-Test.xlsx


curl -k -u 'alice@example.test:<password>' -T ForgeOne-Files-Office-Test.pptx \
 https://mail.example.test/files/remote.php/dav/files/alice@example.test/ForgeOne-Files-Office-Test.pptx
https://mail.example.test/files/

Screenshot: Files shows DOCX, XLSX and PPTX after upload and scan.

Step 13: Edit, save and read back DOCX

The real acceptance test is not merely opening the editor. Type text into the document, save it, close it, download the file again and verify that the change really landed inside the DOCX file.

https://mail.example.test/files/index.php/apps/onlyoffice/29

Screenshot: DOCX in the Office editor with a visible validation change.

https://mail.example.test/files/index.php/apps/onlyoffice/29

Screenshot: After saving, the editor reports that all changes are saved.

bash
curl -k -u 'alice@example.test:<password>' \
 -o /tmp/ForgeOne-Files-Office-Test.docx \
 https://mail.example.test/files/remote.php/dav/files/alice@example.test/ForgeOne-Files-Office-Test.docx


unzip -p /tmp/ForgeOne-Files-Office-Test.docx word/document.xml | grep 'ForgeOne Files Office validation'

Validated result:

  • DOCX opened in the browser.
  • Text was inserted in the editor.
  • Saving reported "All changes saved".
  • WebDAV download returned a valid Microsoft Word file.
  • The marker was present in word/document.xml.

Step 14: Validate XLSX and PPTX

Then validate at least one spreadsheet and one presentation. In the tested environment, both file types opened in the appropriate Office editor.

https://mail.example.test/files/index.php/apps/onlyoffice/30

Screenshot: XLSX opens in the grommunio Office spreadsheet editor.

https://mail.example.test/files/index.php/apps/onlyoffice/31

Screenshot: PPTX opens in the grommunio Office presentation editor.

Step 15: Test sharing with a second user

Files is only practical when sharing works. Share a file from user A to user B and then validate access with a separate session.

bash
curl -k -u 'alice@example.test:<password>' \
 -H 'OCS-APIRequest: true' \
 --data-urlencode 'path=/ForgeOne-Files-Office-Test.docx' \
 -d 'shareType=0' \
 --data-urlencode 'shareWith=bob@example.test' \
 -d 'permissions=15' \
 'https://mail.example.test/files/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json'


curl -k -u 'bob@example.test:<password>' -X PROPFIND -H 'Depth: 1' \
 https://mail.example.test/files/remote.php/dav/files/bob@example.test/
https://mail.example.test/files/

Screenshot: The second user sees the shared DOCX file in their Files account.

Step 16: Integrate Webmail, Files and Office

Check Files and Office standalone first. If the grommunio Web/Files integration is enabled in your environment, then verify both mail workflows directly in the web client.

Workflow A: add a grommunio Files document as a mail attachment

  • ✓ New email in grommunio Web: The composer opens.

  • ✓ Add attachment: The attachment dialog is reachable.

  • ✓ Select grommunio Files: The Files entry is visible when the integration is enabled.

  • ✓ Open folder and select file: An existing file can be selected.

  • ✓ Send mail: The file is visible as an attachment and arrives at the recipient.

Workflow B: save a received mail attachment to grommunio Files

  • ✓ Open mail with attachment: The attachment is visible in grommunio Web.

  • ✓ Open attachment actions: The save-to-Files action is visible when the integration is enabled.

  • ✓ Select target folder: The target folder in Files can be selected.

  • ✓ Save and verify: The file is then visible in the target folder in Files.

Workflow C: edit an Office document

  • ✓ Open document in Files: The document starts in Online Office.

  • ✓ Save change: The change is saved.

  • ✓ Reopen: The change is present after reopening.

Result Validation / Technical Acceptance

Installation

Check
Check packages and components
Expected result
The component is fully installed
Status
PASS

Services

Check
Check systemd services
Expected result
The required services are active
Status
PASS

Network

Check
Check ports and URLs
Expected result
The component is reachable through the intended paths
Status
PASS

Core function

Check
Run standalone test
Expected result
The core function works before deeper integration
Status
PASS

Authentication

Check
Test SSO/login
Expected result
Login works through the intended path or is intentionally not required
Status
PASS or N/A

grommunio Web

Check
Check integration from Web
Expected result
The component is reachable or usable from grommunio Web
Status
PASS or N/A

End-to-end

Check
Test real user workflow
Expected result
The full workflow is reproducibly successful
Status
PASS

Restart

Check
Restart services
Expected result
The function remains available after service restart
Status
PASS

Logs

Check
Check relevant logs
Expected result
No blocking errors in the validated flow
Status
PASS

4. Typical issues & troubleshooting

  • Web UI does not load: check FQDN, TLS, reverse proxy, firewall and service status.

  • Login or SSO fails: check realm, client, redirect URIs, certificate chain, time and user mapping.

  • Feature remains empty: check package level, plugins, permissions, logs and background services.

5. Conclusion & outlook

The grommunio building block is configured and placed in the platform context. The next parts continue the collaboration environment step by step.