Zimbra Collaboration Administrator Guide for On-premise chat and video

Define a subdomain address, something like chat.your-domain.com.

Route the subdomain to the Primary Server Public IP.

Open an SSH session to the Zimbra Chat server and follow the steps below:

Begin the installation

Choose Single-server installation mode.

Which installation mode do you want to execute?

1) Single-server installation.
2) Multi-server installation.

Please, choose one of the options above: 1

Provide Web domain (The subdomain defined for the Zimbra Chat server).

Provide WEB domain (E.g. chat.your-domain.com): chat.your-domain.com

Provide an email address for SSL (Let’s Encrypt) certificate default configuration.

Provide an email address for internal SSL certificates (E.g. support@your-domain.com): support@your-domain.com

Provide SMTP credentials for transactional emails. The application needs to send transactional emails to the users in operations like sign-up, password recovery, contact invites, etc.

Provide SMTP Host (E.g. mail.your-domain.com): mail.your-domain.com

Provide SMTP Port (E.g. 587): 587

Provide SMTP User (E.g. noreply@your-domain.com): noreply@your-domain.com

Provide SMTP Password : 123456

Provide a system admin user password.
Note the system admin user will always be created in the following format:
admin@PROVIDED_WEB_DOMAIN

Provide a system admin user password (admin@chat.your-domain.com): 123456

Wait for a few minutes while the Zimbra Chat is being configured.

After the installation process is done, access chat.your-domain.com on your browser.

Access the Zimbra Chat on the browser.

Sign in as the admin user configured during the installation.

Go to the main menu located at the top-right of the page.

And click on Zimbra Chat Administration.

Log in as zimbra-chat user.

Execute: zimbra-chat logs [api|webmessenger|message-queue|web-v1|web-v2|push-server|file-text-extractor|mongo|redis|rabbitmq|es01|es02|nginx]

Log in as zimbra-chat user.

Execute zimbra-chat stop.

Execute zimbra-chat start.

Log in as zimbra-chat user.

Execute zimbra-chat restart.

Log in as zimbra-chat user.

Execute zimbra-chat status.

Log in as zimbra-chat user.

Execute zimbra-chat monit.

Download the Zimlet package here.

Push zimbra-zimlet-chat-video.zip file to the Zimbra server:

As a zimbra user run the following command to install the Modern Interface’s Zimlet:

Grant permission to Chat and Video domains if they are different from the Zimbra domain:

To configure the Chat and Video URLs in the Zimlet and other properties, create a config template file with the right addresses:

Import the new configuration file by running the following command:

You might need to clear the Zimlet cache to see the new configuration applied

Download the Zimlet package here.

Push com_zimbra_chat_video.zip file to the Zimbra server:

As a zimbra user run the following command to install the Classic Interface’s Zimlet:

Grant permission to Chat and Video domains if they are different from the Zimbra domain:

To configure the Chat and Video URLs in the Zimlet, create a config template file replacing iframeURL and apiURL properties at least by your Chat and Video installation URLs as necessary:

Import the new configuration file by running the following command:

You might need to clear the Zimlet cache to see the new configuration applied:

Log in to Zimbra Server.

Create the directory /opt/zimbra/lib/ext/chat-video if necessary.

If still not, generate the API Keys on the Zimbra Chat server.

Create or copy the config.domains.json file to /opt/zimbra/lib/ext/chat-video/config.domains.json as necessary.

If the config.domains.json file was not generated on the Zimbra Chat server, you need to manually add the API keys. Follow these steps:

*Locate the Configuration File: *Navigate to the directory where the config.domains.json file should be located:

/opt/zimbra/lib/ext/chat-video/

*Edit the Configuration File: *Open or create the config.domains.json file in a text editor.

*Add the API Keys: *Use the following template format to add your API keys:

[
   {
      "domain": "example.com",
      "apiKey": "<your_api_key_here>"
   }
]

Example of multiple domains configuration:

[
   {
      "domain": "abc.com",
      "apiKey": "ee35f524-8362-427f-b5d0-6c0a3a81bcea"
   },
   {
      "domain": "xpto.com",
      "apiKey": "74727ded-c8a3-4b82-9add-561fb5d79a24"
   }
]

*Save the File: *After adding the necessary details, save the changes to config.domains.json.

Restart the mailbox server using:

zmmailboxdctl restart

Create the directory /opt/zimbra/lib/ext/chat-video if necessary.

Download the Java Extension here and move to /opt/zimbra/lib/ext/chat-video if the chat-video.jar file is still not there.

Open the file /opt/zimbra/lib/ext/chat-video/config.properties.

Replace the chatVideoApiURL configuration with your Zimbra Chat on-premises API URL.
E.g.:

chatVideoApiURL=https://chat.your-domain.com/api

Save the file and restart the mailbox server.

For user:

 zmprov ga <EMAIL ADDRESS> | grep -e BasicOneToOne -e AdvancedChat -e AdvancedChatVideo

For COS:

zmprov gc <COS NAME> | grep -e BasicOneToOne -e AdvancedChat -e AdvancedChatVideo

Open an SSH session to the Zimbra Chat server and follow the steps below:

Begin the update.

Wait for a few minutes while the Zimbra Chat is being updated.

After the update process is done, access chat.your-domain.com on your browser.

Check all services' status on the server by running the following steps:

Restart all services by running zimbra-chat restart.

Check DNS configuration and ensure the domain is routed to the Primary Server Public IP.

Check Nginx logs by running zimbra-chat logs nginx and while you try to access the application on the browser ensure the requests are shown on the logs.

On the browser, open the developer tools by pressing CTRL+SHIFT+i and check on the "console" tab for additional error messages.

Check the logs on the Zimbra server.

Ensure you have the Chat/Video features enabled for the user by following the steps described here

Check the ChatAccountsLimit and ChatVideoAccountsLimit on Zimbra server by running zmlicense -c as zimbra user.

If everything loads ok except the messages in a conversation, there is a chance the Websocket service is not working properly.

If after restart the service is still not stable, contact the advanced support team and share any error logs that appear.

Log in to the Zimbra Chat primary server as a zimbra-chat user.

Check the status of the services ElasticSearch 01 and ElasticSearch 02.

Check the logs by running zimbra-chat logs es01 and zimbra-chat logs es02.

Check that port 9200 is open for the Zimbra Chat secondary server.

Check the API logs by running zimbra-chat.sh logs api.

If everything works fine except messages sent via “Compose“, that means the Message Queue service might not be working properly.

Log in to the Zimbra Chat primary server as a zimbra-chat user.

Check the status of Message Queue service by running zimbra-chat status.

Check the logs zimbra-chat logs message-queue.

Look for error messages that can help to find a solution.

Try to restart all the services zimbra-chat restart.

Check the image below for reference:

The Modern UI Zimlet Installation steps might not be followed properly.

Ensure the apiURL and webURL properties were configured with your Chat URL and not the example. Both properties must be replaced with your own Chat URL.

<property name="apiURL">https://chat.company.com/api</property>
<property name="webURL">https://chat.company.com</property>

If you identify the properties misconfigured, repeat the configuration steps here

Check the image below for reference:

A Content Security Policy might be blocking the Chat to loaded in Zimbra interface.

Follow the steps here to allow your Zimbra load the Zimbra Chat properly.

Access the Zimbra Chat server as zimbra-chat user.

Edit the file /opt/zimbra-chat/config.

Find the properties SMTP_HOST, SMTP_USER, SMTP_PASSWORD and SMTP_PORT and make sure the credentials are right and SMTP is working properly.

In the case a change needs to done, update the properties with the right value.

Save the config file.

Restart the Zimbra Chat by running zimbra-chat restart.

Access the Zimbra Chat server as zimbra-chat user.

Check the API logs to make sure the message is being delivered to the server by running zimbra-chat logs api.

Check the Webmessenger logs by running zimbra-chat logs webmessenger.

Check the RabbitMQ logs by running zimbra-chat logs rabbitmq.

Check the Redis logs by running zimbra-chat logs redis.

Collect any error message.

Initially restarting the Zimbra Chat service may be enough to stabilise the application. Try it by running zimbra-chat restart.

In the case restart does not work, try to update the application by following instructions here

If the issue persists, contact support and provide the collected logs.

Access the Zimbra Chat service as zimbra-chat user.

Check the API logs by running zimbra-chat logs api.

Try to execute one message search and check on the logs if the request is reaching the API and if some error is presented.

Check the ElasticSearch logs by running zimbra-chat logs es01 and zimbra-chat logs es02.

Collect any error message.

Initially restarting the Zimbra Chat service may be enough to stabilise the application. Try it by running zimbra-chat restart.

In the case restart does not work, try to update the application by following instructions here

If the issue persists, contact support and provide the collected logs.

Follow the steps here to activate Advanced Chat features to an user or COS.

The changes will be applied after the user reload the Zimbra page.

In the case a error message appears on zimbraFeatureAdvancedChatEnabled activation, your account limits might not be enough.

On Zimbra server as zimbra user, execute zmlicense -p to check your limits.

Look for something like that:

Feature : ChatAccountsLimit
        Status: Authorized for use
        Max Limit: 50
        Used Limit: 50

If used limits are exceeded, you can remove feature from some users or contact Zimbra for an upgrade.

If the limits are not exceeded and Advanced Chat features still not enabled, check the Zimbra logs.

Access the Zimbra server as zimbra user and execute tail -f /opt/zimbra/log/mailbox.log | grep ChatVideo .

Collect the logs and contact support for further assistance.

Follow the steps here to activate Chat and Video to an user or COS.

The changes will be applied after the user reload the Zimbra page.

In the case a error message appears on zimbraFeatureAdvancedChatVideoEnabled activation, your account limits might not be enough.

On Zimbra server as zimbra user, execute zmlicense -p to check your limits.

Look for something like that:

Feature : ChatVideoAccountsLimit
        Status: Authorized for use
        Max Limit: 50
        Used Limit: 0

If used limits are exceeded, you can remove feature from some users or contact Zimbra for an upgrade.

If the limits are not exceeded and Video feature still not enabled, check the Zimbra logs.

Access the Zimbra server as zimbra user and execute tail -f /opt/zimbra/log/mailbox.log | grep ChatVideo .

Collect the logs and contact support for further assistance.

Make sure you followed these steps properly.

Ensure Zimbra Video is installed correctly and running.

Access from your browser the Zimbra Video solution URL directly and check if the application is loaded.

This direct access is only for testing, you will not be able to get in a video session without accessing the Zimbra Chat first.

If the installation or restart is taking too long, check the log file located at /var/log/zimbra-chat-installation.log and look for an error similar to the one below:

npm ERR! code EAI_AGAIN
npm ERR! errno EAI_AGAIN
pm ERR! request to https://registry.npmjs.org/ms/-/xxxxxx.tgz failed, reason: getaddrinfo EAI_AGAIN registry.npmjs.org

Once you identify the message on the logs, follow the configuration steps here to change the default docker0 IP.

Rerun the installation or restart the application, then check if the issue persists or not.

If the issue persists or reappears, it could indicate DNS issues related to your network. Please double-check your DNS configuration.

For further assistance, contact the support team.

Ensure that Docker logs rotation is configured to prevent that.

Check if the Zimbra Chat storage located in /opt/zimbra-chat/storage is causing the issue. If so, it is recommended to either expand the existing storage or migrate to an instance with more storage capacity.

Before starting the import process, ensure that your Zimbra Chat server has at least three times the size of the .tgz file available as free space.

For example, if the .tgz file is 200GB, you will need at least 600GB of free space on the server.

Try to run the chat import process only once to avoid complications.

If a second chat import is necessary, ensure that no user accounts have been recreated in Zimbra.

To prevent conflicts, consider exporting chat data from Zimbra in smaller batches.
The chat export feature lets you export users based on domain name, specific email address, or a list of email addresses. For more details, refer to the documentation here.

Verify that the name of the exported TGZ file from Zimbra is correct.

Confirm that the TGZ file is located in the correct directory: /opt/zimbra-chat/import.

Ensure that the zimbra-chat user has the necessary permissions to access the file.

Open your browser’s developer tools (usually F12 or Ctrl+Shift+I) and switch to the Console tab.

Look for any errors related to AngularJS. You should see a message similar to the following:

If you see an error like the one above, it means that the AngularJS module is not loaded properly.

To fix this issue, restart the Zimbra Chat one more time by running zimbra-chat restart.

Open the Zimbra Chat URL in a different tab out of Zimbra and hard reload the page (usually Ctrl+Shift+R) to avoid cache.

Return to the Zimbra interface and verify that the Zimbra Chat module is loading correctly.