# Set Up grommunio Chat 2026: Teams, Channels, Users and Multi-Tenancy Testing Source: https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step Language: en Published: 2026-09-05 Updated: 2026-10-22 Practical guide for grommunio Chat: installation, database, nginx upstream, domain teams, WebSockets, two users and multi-tenancy. ## 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 enable, operate and test grommunio Chat on an existing grommunio 2026 appliance with multiple users. The guide covers services, web access, users, teams, channels, permissions, WebSockets, multi-tenancy, logs and a reproducible acceptance check. ## 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 ### Prerequisites An existing or planned grommunio environment, matching DNS names, TLS, administrative access and a clear target for mail, collaboration or operations. This guide shows how to install, configure and test grommunio Chat on an existing grommunio 2026.06.1 appliance with multiple users. The goal is not just that \`/chat/\` loads. Teams, channels, WebSocket connectivity, user privileges and domain mapping need to work together. - You install grommunio Chat 10 from the grommunio repository. - You configure database, Chat configuration, local admin and admin API integration. - You enable Chat per domain and per user. - You validate the nginx upstream for \`/chat/\`. - You test two users in the same team and channel. - You evaluate what is multi-tenant capable and when a separate installation is required. The series remains chronological: [install grommunio](https://forgeone.solutions/en/tech/install-grommunio-2026), [antispam with Rspamd](https://forgeone.solutions/en/tech/grommunio-antispam-rspamd-2026-step-by-step), [SSO with Keycloak](https://forgeone.solutions/en/tech/grommunio-auth-keycloak-2026-step-by-step), [Meet with Jitsi](https://forgeone.solutions/en/tech/grommunio-meet-2026-step-by-step) and now Chat. Product context is available on the [grommunio product page](https://forgeone.solutions/en/products/grommunio). ### Architecture: what grommunio Chat is grommunio Chat is the team communication layer inside the grommunio platform and is technically based on Mattermost. The appliance runs the Chat service locally and exposes it through nginx under \`/chat/\`. grommunio Admin keeps the mapping between grommunio domain, grommunio user and Chat team. - Browser - https://mail.example.test/chat/ - nginx location /chat/ - upstream chat\_server - grommunio-chat on 127.0.0.1:8065 - MariaDB database grochat - domain Chat team and user mapping through grommunio Admin ### Step 1: Install the package and check the state First check whether Chat is already installed. On the validated appliance only the admin driver was present; the actual Chat server had to be installed. ```bash rpm -qa | grep -Ei 'grommunio-chat|mattermost' | sort zypper search -s grommunio-chat zypper --non-interactive install --auto-agree-with-licenses grommunio-chat-v10 ``` ### Step 2: Prepare database and configuration Chat needs its own database and a \`config.json\`. Use unique passwords and never paste them into tickets, screenshots or articles. In production runbooks these values belong in secret management or at least in root-readable files. ```bash install -d -m 0750 -o grochat -g grochat /etc/grommunio-chat /var/log/grommunio-chat /var/lib/grommunio-chat cp -n /etc/grommunio-chat/config.json.example /etc/grommunio-chat/config.json # Beispiel: Datenbank und Benutzer anlegen. # Ersetze durch ein starkes Secret. mariadb <<'SQL' CREATE DATABASE IF NOT EXISTS grochat CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER IF NOT EXISTS 'grochat'@'localhost' IDENTIFIED BY ''; GRANT ALL PRIVILEGES ON grochat.* TO 'grochat'@'localhost'; FLUSH PRIVILEGES; SQL ``` In \`config.json\`, at minimum \`SiteURL\`, SQL driver, SQL data source and local mode must be correct. The \`SiteURL\` must match the URL users actually use in the browser. In validation, a mismatched port/origin combination produced WebSocket 403 errors. ```bash python3 - <<'PY' import json from pathlib import Path path = Path('/etc/grommunio-chat/config.json') data = json.loads(path.read_text()) data['ServiceSettings']['SiteURL'] = 'https://mail.example.test/chat' data['ServiceSettings']['ListenAddress'] = '127.0.0.1:8065' data['ServiceSettings']['EnableLocalMode'] = True data['ServiceSettings']['LocalModeSocketLocation'] = '/var/tmp/grommunio-chat_local.socket' data['SqlSettings']['DriverName'] = 'mysql' data['SqlSettings']['DataSource'] = 'grochat:@tcp(localhost:3306)/grochat?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s' data['TeamSettings']['EnableOpenServer'] = False data['TeamSettings']['RestrictCreationToDomains'] = 'example.test' path.write_text(json.dumps(data, indent=2) + '\n') PY chown grochat:grochat /etc/grommunio-chat/config.json chmod 0640 /etc/grommunio-chat/config.json ``` ### Phase B - normal Chat test before Keycloak The normal Chat test comes before the Keycloak integration: open Chat, use the intended baseline login, verify team and channel, user A sends a message, user B sees it and replies. ### Step 3: Start the service and validate nginx upstream Start Chat and verify the local socket. On the validated appliance it was also important to activate the shipped nginx upstream file from the \`.example\` file. Without this upstream, \`nginx -t\` failed with \`host not found in upstream "chat\_server"\`. ```bash systemctl enable --now grommunio-chat test -S /var/tmp/grommunio-chat_local.socket cp -n /etc/grommunio-common/nginx/upstreams.d/grommunio-chat.conf.example \ /etc/grommunio-common/nginx/upstreams.d/grommunio-chat.conf nginx -t systemctl restart nginx grommunio-admin-api curl -kI https://mail.example.test/chat/ curl -k https://mail.example.test/chat/api/v4/system/ping ``` ### Step 4: Connect local Chat admin and admin API grommunio Admin needs a technical Chat admin so domains and users can be mirrored into Chat. Use an address inside the allowed domain. If you set \`RestrictCreationToDomains = example.test\`, \`admin@localhost\` is deliberately not allowed. ```bash export MMCTL_LOCAL_SOCKET_PATH=/var/tmp/grommunio-chat_local.socket /usr/share/grommunio-chat/bin/grommunio-chat-ctl --local user create \ --email groadmin@example.test \ --username groadmin \ --password '' \ --system-admin \ --email-verified \ --disable-welcome-email cat >/etc/grommunio-admin-api/conf.d/chat.yaml <<'YAML' chat: connection: login_id: groadmin password: '' url: mail.example.test basepath: /chat/api/v4 port: 443 scheme: https verify: False YAML chmod 0600 /etc/grommunio-admin-api/conf.d/chat.yaml systemctl restart grommunio-admin-api ``` ### Step 5: Enable domain and users Enable Chat on the domain first. Only then can users be linked to Chat reliably. In validation, \`grommunio-admin domain modify example.test --chat true\` created a Chat team for this domain. ### Step 6: Test login and channels Open Chat with a normal user. After the first login, the domain team must be visible. In this guide, team and channel names are synthetic, but the flow is identical to a production environment. [![Login to grommunio Chat through the validated example environment.](https://forgeone.solutions/media/grommunio-chat-2026-01-login.png)](https://forgeone.solutions/media/grommunio-chat-2026-01-login.png) Screenshot: Login to grommunio Chat through the Chat route. [![Team overview after the first successful Chat login.](https://forgeone.solutions/media/grommunio-chat-2026-02-team-overview.png)](https://forgeone.solutions/media/grommunio-chat-2026-02-team-overview.png) Screenshot: After login, the user sees the domain team and default channels. Then create functional channels. The example environment used \`Operations\` and \`Project\` because they represent typical collaboration boundaries. ```bash export MMCTL_LOCAL_SOCKET_PATH=/var/tmp/grommunio-chat_local.socket TEAM="$(/usr/share/grommunio-chat/bin/grommunio-chat-ctl --local team list --json \ | jq -r '.[0].name')" /usr/share/grommunio-chat/bin/grommunio-chat-ctl --local channel create \ --team "$TEAM" \ --name betrieb \ --display-name "Betrieb" \ --purpose "Abstimmung für Betrieb, Monitoring und Tagesbetrieb." /usr/share/grommunio-chat/bin/grommunio-chat-ctl --local channel users add "$TEAM:betrieb" alex meet ``` [![Operations channel with active user and visible channel structure.](https://forgeone.solutions/media/grommunio-chat-2026-03-channel-betrieb.png)](https://forgeone.solutions/media/grommunio-chat-2026-03-channel-betrieb.png) Screenshot: The Operations channel is visible for the first user. [![Second user in the same Chat team and channel.](https://forgeone.solutions/media/grommunio-chat-2026-04-second-user-channel.png)](https://forgeone.solutions/media/grommunio-chat-2026-04-second-user-channel.png) Screenshot: A second user sees the same team and the same channel. ### Step 7: Multi-user and WebSocket test Always test Chat with two separate browser contexts or two devices. A working login page is not enough. The message must become visible for the second user without a reload. This is where incorrect \`SiteURL\`, reverse proxy or WebSocket configuration becomes visible. [![First test message in the Operations channel after successful WebSocket configuration.](https://forgeone.solutions/media/grommunio-chat-2026-05-message-sent.png)](https://forgeone.solutions/media/grommunio-chat-2026-05-message-sent.png) Screenshot: The first user sends a message in the Operations channel. [![The second user sees the same chat message in the same channel.](https://forgeone.solutions/media/grommunio-chat-2026-06-message-visible.png)](https://forgeone.solutions/media/grommunio-chat-2026-06-message-visible.png) Screenshot: The second user sees the same message in the same channel. ```bash Acceptance criteria: - /chat/ returns HTTP 200 - /chat/api/v4/system/ping returns status OK - WebSocket has no 403 handshake error - two users see the same domain team - both users see the same channel - a message becomes visible for the second user - nginx -t succeeds - grommunio-chat, nginx, mariadb and grommunio-admin-api are active ``` ### Step 2a: Connect Chat SSO with grommunio-auth and Keycloak When grommunio-auth is used as the central login, Chat gets its own confidential OpenID Connect client in the grommunio Keycloak realm. Open Keycloak administration through grommunio-auth, switch to the \`grommunio\` realm and first check whether the client already exists. The appliance uses the Mattermost-compatible GitLab OAuth integration of grommunio Chat here. Create the client if it is missing: \`Create client\`, client type \`OpenID Connect\`, client ID \`grommunio-chat\`. Afterwards keep \`Client authentication\` and \`Standard flow\` enabled, while \`Direct access grants\`, \`Implicit flow\` and \`Service account roles\` stay disabled. [![Keycloak client grommunio-chat with confidential OIDC client enabled.](https://forgeone.solutions/media/grommunio-suite-sso-2026-13-keycloak-chat-client-settings.png)](https://forgeone.solutions/media/grommunio-suite-sso-2026-13-keycloak-chat-client-settings.png) Screenshot: The Chat client is a confidential OIDC client with standard flow enabled. Then enter the real browser URLs. On the validated appliance both Mattermost-compatible callback paths were relevant because Chat can return through different login and signup flows. - Valid redirect URIs: - https://mail.example.test/chat/login/gitlab/complete - https://mail.example.test/chat/signup/gitlab/complete - Web origins: - https://mail.example.test [![Redirect URIs and web origin of the grommunio-chat client.](https://forgeone.solutions/media/grommunio-suite-sso-2026-14-keycloak-chat-redirects.png)](https://forgeone.solutions/media/grommunio-suite-sso-2026-14-keycloak-chat-redirects.png) Screenshot: The redirect URIs must exactly match the appliance’s published \`/chat\` path. The grommunio-auth adapter script writes the Chat integration into the Mattermost-compatible \`GitLabSettings\` in \`/etc/grommunio-chat/config.json\`. On this appliance, this is the supported technical path for the Keycloak login button in Chat. Client secrets belong in the adapter configuration, not in screenshots, tickets or articles. ```bash /usr/share/grommunio-auth/adaptor-config-scripts/setup-gk-app-g-chat jq '.GitLabSettings | { Enable, Id, AuthEndpoint, TokenEndpoint, UserAPIEndpoint, DiscoveryEndpoint, ButtonText }' /etc/grommunio-chat/config.json systemctl restart grommunio-chat ``` [![grommunio Chat login with enabled Keycloak SSO button.](https://forgeone.solutions/media/grommunio-suite-sso-2026-06-chat-sso-login.png)](https://forgeone.solutions/media/grommunio-suite-sso-2026-06-chat-sso-login.png) Screenshot: After adapter configuration, grommunio Chat shows the Keycloak login button on the real \`/chat\` URL. ### Login test with Keycloak - Chat -> Keycloak -> login/MFA -> redirect -> Chat -> team/channel: to be verified from the intended user workflows. - 2-user chat after SSO: optional to be verified in this recheck. ### Final grommunio Web test for Chat The Web test is complete only when the user moves from grommunio Web into Chat, completes SSO and exchanges messages in the team/channel with a second user. In the current recheck, the full Web->Chat->2-user path remains to be verified/optional to be verified for the second-user reply without new live proof. ## Result Validation / Technical Acceptance | Test area | Check | Expected result | Status | | --- | --- | --- | --- | | Installation | Check packages and components | The component is fully installed | PASS | | Services | Check systemd services | The required services are active | PASS | | Network | Check ports and URLs | The component is reachable through the intended paths | PASS | | Core function | Run standalone test | The core function works before deeper integration | PASS | | Authentication | Test SSO/login | Login works through the intended path or is intentionally not required | PASS or N/A | | grommunio Web | Check integration from Web | The component is reachable or usable from grommunio Web | PASS or N/A | | End-to-end | Test real user workflow | The full workflow is reproducibly successful | PASS | | Restart | Restart services | The function remains available after service restart | PASS | | Logs | Check relevant logs | No blocking errors in the validated flow | PASS | ## 4. Typical issues & troubleshooting The validated appliance can link each grommunio domain to its own Chat team. In the countercheck, a second domain created a second team. This is useful for organisational separation, but it is not hard platform isolation. - Suitable inside one shared installation: separate domain teams, public and private channels, team members, roles at team/channel level, controlled invites and direct messages inside the platform. - Only partially multi-tenant capable: global Chat server configuration, plugins, webhooks, bots, email notifications, file storage, system console, search index, global retention and compliance features. - Separate installation recommended: separate customers with hard privacy boundaries, separate administrators, separate SSO, separate backup/restore requirements, separate plugins/integrations or different security policies. - In a grommunio groupware environment, one domain team per tenant is useful for internal organisational areas. For managed-service customers with real isolation requirements, plan separate grommunio installations. ```bash grommunio-admin domain create tenant2.test -u 10 --title "Tenant 2 Test" --chat true grommunio-admin domain query domainname title chat chatID --format json-flat # Erwartung: # example.test -> eigenes Chat-Team # tenant2.test -> eigenes Chat-Team ``` ## Sources Vendor and upstream documentation used: - [grommunio documentation](https://docs.grommunio.com/) - [grommunio downloads and release information](https://download.grommunio.com/) - [grommunio Chat documentation](https://docs.grommunio.com/) ## Use grommunio Chat in production? ForgeOne supports chat enablement, permissions, WebSockets, multi-tenancy, operations and support. - [Discuss your Chat project](https://forgeone.solutions/en/contact) ## Hero image [![Operations channel with active user and visible channel structure.](https://forgeone.solutions/media/grommunio-chat-2026-03-channel-betrieb.png)](https://forgeone.solutions/media/grommunio-chat-2026-03-channel-betrieb.png) ## Author Mathias Rumbold ## Category - [grommunio & Groupware](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?category=grommunio-groupware) ## Tags - [grommunio](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=grommunio) - [grommunio Chat](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=grommunio-chat) - [Mattermost](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=mattermost) - [Collaboration](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=collaboration) - [Groupware](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=groupware) - [Digital Sovereignty](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=digitale-souveraenitaet) - [Multi-tenancy](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=mandantenfaehigkeit) - [Native Exchange Replacement](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step?tags=native-exchange-replacement) ## Integrate grommunio Chat properly ForgeOne supports teams, channels, user flows, SSO and operations for grommunio Chat. [Discuss chat integration](https://forgeone.solutions/de/produkte/grommunio/grommunio-chat) ## grommunio 2026 Schritt für Schritt Die Beiträge bauen chronologisch aufeinander auf: Installation, Security, SSO, Module, Betrieb, Migration, Upgrade und Client-Abnahme. Veröffentlichte Teile werden automatisch verlinkt; geplante Fortsetzungen bleiben sichtbar, aber ohne 404-Link. 1. [Install grommunio 2026.06.1: From ISO to Working Groupware](https://forgeone.solutions/en/tech/install-grommunio-2026) 2. [grommunio-antispam with Rspamd: Spam Filtering, Learning and Operations Step by Step](https://forgeone.solutions/en/tech/grommunio-antispam-rspamd-2026-step-by-step) 3. [grommunio-auth with Keycloak: SSO and central login step by step](https://forgeone.solutions/en/tech/grommunio-auth-keycloak-2026-step-by-step) 4. [Set up grommunio Meet 2026 without Keycloak and optionally add SSO](https://forgeone.solutions/en/tech/grommunio-meet-2026-step-by-step) 5. [Set Up grommunio Chat 2026: Teams, Channels, Users and Multi-Tenancy Testing (current part)](https://forgeone.solutions/en/tech/grommunio-chat-2026-step-by-step) 6. [Set Up grommunio Files and Office: Validate Files, Web Entry and Online Office](https://forgeone.solutions/en/tech/grommunio-files-office-2026-step-by-step) 7. [Set Up grommunio Archive 2026: Archive, Search and Restore Email](https://forgeone.solutions/en/tech/grommunio-archive-2026-step-by-step) 8. [grommunio MDM 2026 step by step: manage ActiveSync devices safely](https://forgeone.solutions/en/tech/grommunio-mdm-2026-step-by-step) 9. [grommunio Multitenancy 2026: organizations, domains and multiple LDAP sources](https://forgeone.solutions/en/tech/grommunio-multitenancy-2026-step-by-step) 10. [grommunio 2026 Cluster and High Availability: from multi-server lab to tested active/standby homeserver](https://forgeone.solutions/en/tech/grommunio-cluster-ha-2026-step-by-step) 11. [grommunio 2026 disaster recovery and single mailbox restore: backup, full DR and targeted mailbox recovery in the lab](https://forgeone.solutions/en/tech/grommunio-disaster-recovery-single-mailbox-restore-2026-step-by-step) 12. [Migrate IMAP mailboxes to grommunio with imapsync](https://forgeone.solutions/en/tech/grommunio-imap-migration-imapsync-2026-step-by-step) 13. [grommunio: Replace Public Folders with a functional mailbox - step by step](https://forgeone.solutions/en/tech/grommunio-public-folder-functional-mailbox-multiple-domains) 14. [grommunio Web 5.0 in the lab: settings namespace, shared mailboxes and admin impact](https://forgeone.solutions/en/tech/grommunio-web-5-0-in-the-lab) 15. [grommunio 2026.06.2 Upgrade and Technical Acceptance: Keycloak SSO, MFA, AutoDiscover and Mail Flow](https://forgeone.solutions/en/tech/grommunio-2026-06-2-upgrade-keycloak-sso-practice) 16. [grommunio native clients after Keycloak SSO: Thunderbird, Outlook, EWS, EAS and MFA explained](https://forgeone.solutions/en/tech/grommunio-native-clients-after-keycloak-sso) 17. grommunio Monitoring und Alerting im Betrieb 18. grommunio Security Hardening in der Praxis 19. grommunio Operations Troubleshooting: typische Fehler sauber eingrenzen