Using Docker to Spin Up a Kopano Environment

June 14, 2019

Written by
Categories: blog, Kopano Meet

In my previous blog, I showed you some of the mechanics that have been used to build containers for Kopano. This time I want to give you a quick rundown on the steps needed to spin up these containers in your local environment. With the below instructions, you will be able to spin up a quick Kopano demo setup (already equipped with some demo users) to test out our newest developments such as Kopano Meet, our OpenID Provider Kopano Konnect and of course our new RestAPI.

Docker and Docker Compose make it trivial to get started with new applications. Instead of first (manually) downloading packages and their dependencies, configuring everything and then eventually being able to run the software, containers make it possible to directly start using it.

The following instructions are meant to be run on a freshly installed system with only Docker, Docker Compose and Git as a requirement. Already installed components (like a webserver) could interfere with the below instructions. In addition to this the machine should have at least 2 GB of available ram.

Clone the git repository to easily stay up to date

All the files of the project itself are stored in a git repository, so when working with kopano-docker it is recommended to clone the repository first to the local machine:

$ git clone https://github.com/zokradonh/kopano-docker
[..]
$ cd kopano-docker

Run setup.sh to configure containers for your environment

The kopano-docker project bundles a small setup script to help setting up required files and settings for the first run of the containers. For q quick and easy setup one can just accept all the suggested defaults by pressing “Enter”.

In the first part of the setup script the user can choose which “tag” to use for the local environment. “latest” will always use the newest available version from the Docker Hub (which uses the Kopano nightly downloads). Using “latest” is of course convenient, but also takes away the choice of when to perform an update.

$ ./setup.sh
Creating individual env files for containers (if they do not exist already)
Creating an .env file for you
Which tag do you want to use for Kopano Core components? [latest]:
Which tag do you want to use for Kopano WebApp? [latest]:
Which tag do you want to use for Z-Push? [latest]:
Which tag do you want to use for Kopano Konnect? [latest]:
Which tag do you want to use for Kopano Kwmserver? [latest]:
Which tag do you want to use for Kopano Meet? [latest]:
Which tag do you want to use for Kopano kDAV? [latest]:

The next set of questions is controls how you can access the running containers afterwards. For the FQDN/Hostname one should use the name that the system running the containers is reachable under. If the system is reachable from the internet on port 80 (and subsequently on port 443) then you could specify here your email address to retrieve a certificate from Let’s Encrypt.

Name of the Organisation for LDAP [Kopano Demo]:
FQDN to be used (for reverse proxy).
        Tipp: use port 2015 in case port 443 is already in use on the system.
        [kopano.demo]:
Email address to use for Lets Encrypt.
        Use 'self_signed' as your email to create self signed certificates.
        Use 'off' if you want to run the service without tls encryption. Make sure to use an ssl-terminating reverse proxy in front in this case.
        [self_signed]:

Afterwards, the script presents questions on where to look up users. In case of a different LDAP server than ldap://ldap:389 is specified the script will ask additional questions regarding the search base and bind user.

Name of the BASE DN for LDAP [dc=kopano,dc=demo]:
LDAP server to be used (defaults to the bundled OpenLDAP) [ldap://ldap:389]:
Use bundled LDAP with demo users? yes/no [yes]:
Timezone to be used [Europe/Berlin]:
E-Mail Address displayed for the 'postmaster' []:

A similar case exists for the (MySQL) database. You can use the bundled one by accepting the default or specify a different hostname, which will trigger additional questions in regards to the database name and username/password for the database.

Name/Address of Database server (defaults to the bundled one) [db]:

In the last part of the setup script, the user can interactively choose additional plugins for WebApp. These plugins will then be installed directly after the WebApp container has started.

Available options:
  1 ) de-at
  2 ) de-ch
  3 ) de-de
  4 ) en
  5 ) en-gb
  6 ) es
  7 ) fr
  8 ) it
  9 ) nl
 10 ) pl-pl
Check language spell support (again to uncheck, ENTER when done):
Available options:
  1 ) contactfax
  2 ) desktopnotifications
  3 ) filepreviewer
  4 ) files
  5 ) filesbackend-smb
  6 ) filesbackend-owncloud
  7 ) folderwidgets
  8 ) gmaps
  9 ) intranet
 10 ) mattermost
 11 ) mdm
 12 ) pimfolder
 13 ) quickitems
 14 ) smime
 15 ) titlecounter
 16 ) webappmanual
 17 ) zdeveloper
Check for additional plugins (again to uncheck, ENTER when done):
Integrate WhatsApp into DeskApp yes/no [no]:

Once the script has finished running all you need to do before logging into Kopano WebApp is issuing a docker-compose up -d (-d here stands for “detached”, meaning that the processes will be started in the background and you are safe to close the terminal). When running this command for the first time it will pull the specified images, startup containers and then you will be able to open “https://your-fqdn/” which will redirect you to the Kopano WebApp login.

In case you are using the built-in LDAP server including our demo users then you will be able to login with one of our demo users (usernames are user1user23, the password is always the same as the username).

In case you are using your own LDAP server or generally want to customise the setup a bit further just have a look at the file named .env. Make sure to check out the individual README files for instructions on configuring parts that are not covered by the .env file.

Using kopano-docker with the official and supported Kopano releases

At Kopano we are earning our money by selling subscriptions, which will give direct access to our support and consulting staff and quality checked versions. With your subscription key, you have access to the Kopano package repositories which enable you to easily (re-)build containers with the desired release.

All that needs to be done for this is to uncomment the below section in the .env file and replace REPLACE-ME with your actual subscription key:

# Modify below to build a different version, than the kopano nightly release
#KOPANO_CORE_REPOSITORY_URL=https://serial:/supported/core:/final/Debian_9.0/
#KOPANO_MEET_REPOSITORY_URL=https://serial:/supported/meet:/final/Debian_9.0/
#KOPANO_WEBAPP_REPOSITORY_URL=https://serial:/supported/webapp:/final/Debian_9.0/
#KOPANO_WEBAPP_FILES_REPOSITORY_URL=https://serial:/supported/files:/final/Debian_9.0/
#KOPANO_WEBAPP_MDM_REPOSITORY_URL=https://serial:/supported/mdm:/final/Debian_9.0/
#KOPANO_WEBAPP_SMIME_REPOSITORY_URL=https://serial:/supported/smime:/final/Debian_9.0/
#KOPANO_ZPUSH_REPOSITORY_URL=http://repo.z-hub.io/z-push:/final/Debian_9.0/
#RELEASE_KEY_DOWNLOAD=1
#DOWNLOAD_COMMUNITY_PACKAGES=0

But please be aware the resulting image will also include your subscription key, therefore, you should not push these images to a public container repository. If you are using your own private repository you can also adapt the docker_repo option in the .env file:

# Docker Repository to push to/pull from
docker_repo=zokradonh

One these changes have been done all you need to do is run make build-all to rebuild the containers with the new repository configuration.

Updating to a more recent version

Now that you have a containerized setup of Kopano running another important aspect is: “How can I update this setup once there is a newer version?”

Updating is almost as easy as getting started in the first place. At first you should execute a git pull within your checked out directory to retrieve the newest version of docker-compose.yml.

After the git repository has been updated you should update your .env to make sure that it references your desired version:

CORE_VERSION=8.7.81.48.39640ec78
WEBAPP_VERSION=3.5.6.2298
ZPUSH_VERSION=2.5.0
KONNECT_VERSION=0.23.4
KWM_VERSION=0.15.3
MEET_VERSION=0.20.0_0
KDAV_VERSION=latest

Once that is done simply pull in the newer images by running docker-compose pull and once this has finished run again a docker-compose up -d to recreate the local containers based on the desired version.

Make sure to check the README of kopano-docker for some more example commands if you are unfamiliar with Docker and docker-compose.

Looking forward to your feedback!

So now one question remains: Is Docker now a supported platform for Kopano?

Well, not exactly. While the above-explained project makes it easy for our partners & customers to build containers locally with our supported packages we still want to gather more feedback on the images themselves before making them a supported product of their own. But you dear reader have the power to influence this: use this container, provide feedback, report issues and (even better) open pull requests on Github for problems you have encountered and functionality you want to add or improve.