Univention Mattermost app¶
This section contains instructions specific to the Mattermost app for Univention.
Installing the app¶
The app can easily be installed from the Univention Appcenter. The app is available for UCS 4.2 (and newer).
The app automatically creates a first user and team for you, so you can already login the username administrator. The password for this user is the one that you specified during the installation (it defaults to mattermost).
Once logged in as administrator you can open the System console from within Mattermost for further configuration of Mattermost itself. In case you have a Mattermost license key you can upload it from the “Edition and License” screen to automatically enable LDAP user management functionality.
If you want to test out the advanced functionality of the Mattermost Enterprise Edition you can request a trial license.
Regardless if you are using LDAP as a user source, or let users join with their email address, you either need to create a new team for your users, invite your users to your team, or make your team public to any signed in user by setting Allow any user with an account on this server to join this team to yes from withing the Team Settings.
Further information can be found in the Mattermost Administrator’s Guide.
Running the app¶
In its default configuration the app may require you to open up additional ports in your firewall, since Mattermost is currently exposed in Port 8123 (http) and 8234 (https). These ports are automatically configured in the UCS firewall, but may need to be added to external firewalls.
Additionally some redirects inside the app (links in mail notifications) are configured to the dns name of the UCS host the app is installed on. Please make sure that the dns name of the UCS host resolves properly.
Starting with the 4.3.1 update its also possible to define a custom hostname and ssl certificate for Mattermost. In case a custom hostname is configured Mattermost will be available through the Ports 80 and 443.
Managing users¶
This app installs the Enterprise Edition of Mattermost. All UCS users can log in to Mattermost with a valid license key. Without a valid license key, only the free-of-charge team edition functions are available. If you want to test out the advanced functionality of the Mattermost Enterprise Edition you can request a trial license.
Command line access¶
In case you want to use the Mattermost Command line tools the you can easily get a shell inside of the Mattermost app container by executing ùnivention-app shell mattermost. If you already know the commands you want to execute, then these commands can easily be chained to the entry of the container:
$ univention-app shell mattermost mattermost-platform version
{"level":"info","ts":1541083311.0965855,"caller":"utils/i18n.go:78","msg":"Loaded system translations for 'en' from '/opt/mattermost/i18n/en.json'"}
{"level":"info","ts":1541083311.0968325,"caller":"app/app.go:204","msg":"Server is initializing..."}
{"level":"info","ts":1541083311.1056023,"caller":"sqlstore/supplier.go:209","msg":"Pinging SQL master database"}
{"level":"info","ts":1541083311.1078012,"caller":"sqlstore/channel_store_experimental.go:47","msg":"Enabling experimental public channels materialization"}
{"level":"info","ts":1541083311.1735156,"caller":"app/license.go:44","msg":"License key from https://mattermost.com required to unlock enterprise features."}
Version: 5.4.0
Build Number: 5.4.0
Build Date: Tue Oct 16 16:48:31 UTC 2018
Build Hash: d5b613cb1bbdaa856fa126e7102d94783b9e80b6
Build Enterprise Ready: true
DB Version: 5.4.0
Backup¶
Starting with version 4.3.0 the app creates a daily backup job that dumps the contents of the bundled MySQL database into the folder /var/lib/univention-appcenter/apps/mattermost/data/backup.
In addition to the MySQL database the folders config and files should be backed up as well.
Restoring a MySQL dump in the Docker container¶
A backup of the MySQL database can be restored when the following steps are followed (all existing MySQL data will be overwritten!):
# 1. check the currently used image by executing docker ps
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3e0a6b5be730 docker.software-univention.de/univention-mattermost:4.4.2 "/start.sh" 5 days ago Up 6 seconds 0.0.0.0:8065->8065/tcp tiny_cori
# in above example the current image is docker.software-univention.de/univention-mattermost:4.4.2
# 2. Stop the currently running container
systemctl stop docker-app-mattermost.service
# 3. start up a new container based on the current image, but override the default entrypoint
docker run -it --entrypoint=bash \
-v /var/lib/univention-appcenter/apps/mattermost/data/files:/opt/mattermost/data \
-v /var/lib/univention-appcenter/apps/mattermost/data/mysql:/var/lib/mysql \
-v /var/lib/univention-appcenter/apps/mattermost/data/config:/etc/mattermost \
--name=mattermost-repair docker.software-univention.de/univention-mattermost:4.4.2
root@a12dbfebece0:/#
# 4. you now have a prompt in your repair environment and can restore the MySQL dump. Before restoring the dump you have to start MySQL first.
root@a12dbfebece0:/# service mysql start
# The password of the MySQL root user is "mysql"
# 5. once you are done type exit to stop the container. The container can permanently be removed by running
root@a12dbfebece0:/# exit
$ docker rm mattermost-repair
Logs & Troubleshooting¶
Following Docker best practices the App does not write logs into files, but instead to the STDOUT of the container. These logs can be viewed the following way.
Get logs by running docker logs -f and giving the name of the Docker container, the name can easily be retrieved from the Univention Configuration Registry:
$ docker logs -f $(ucr get appcenter/apps/mattermost/container)
...
[2017/10/26 10:23:20 UTC] [INFO] Config file watcher detected a change reloading /etc/mattermost/config.json
[2017/10/26 10:23:23 UTC] [INFO] Config file watcher detected a change reloading /etc/mattermost/config.json
=> Start MySQL
* Starting MySQL database server mysqld
...done.
=> Start Mattermost
[2017/10/29 07:45:06 UTC] [INFO] Loaded system translations for 'en' from '/opt/mattermost/i18n/en.json'
[2017/10/29 07:45:06 UTC] [INFO] Current version is 4.3.0 (4.3.1/Fri Oct 20 20:02:36 UTC 2017/c8a67ac3c95b11b6a3045905cd4f875f8ffd0fe8/729b149c2a5c82c230e302f0963f6161ca7c652e)
[2017/10/29 07:45:06 UTC] [INFO] Enterprise Enabled: true
[2017/10/29 07:45:06 UTC] [INFO] Current working directory is /opt/mattermost
[2017/10/29 07:45:06 UTC] [INFO] Loaded config file from /etc/mattermost/config.json
[2017/10/29 07:45:06 UTC] [INFO] Able to write files to local storage.
[2017/10/29 07:45:06 UTC] [INFO] Server is initializing...
[2017/10/29 07:45:06 UTC] [INFO] Pinging SQL master database
[2017/10/29 07:45:07 UTC] [INFO] License key from https://mattermost.com required to unlock enterprise features.
[2017/10/29 07:45:07 UTC] [INFO] Initializing plugin: ldapextras
[2017/10/29 07:45:07 UTC] [INFO] Initializing plugin: jira
[2017/10/29 07:45:07 UTC] [INFO] Initializing job API routes
[2017/10/29 07:45:07 UTC] [INFO] API version 3 is scheduled for deprecation. Please see https://api.mattermost.com for details.
[2017/10/29 07:45:07 UTC] [INFO] Starting 4 websocket hubs
[2017/10/29 07:45:07 UTC] [INFO] Starting Server...
[2017/10/29 07:45:07 UTC] [INFO] Server is listening on :8065
[2017/10/29 07:45:07 UTC] [INFO] Starting workers
[2017/10/29 07:45:07 UTC] [INFO] Starting schedulers.
...
In case case the app does not start up anymore and the admin wants to remove it, this action will fail since Univention requires a running container to perform a last backup before removal. The following command can be used from the commandline of the UCS system to force the removal: univention-app remove mattermost –do-not-backup