Kontalk server Docker images
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
config Separated directories for config templates and real config files Jun 13, 2017
httpupload Docker base image is now Debian 9.0 Stretch Jun 22, 2017
letsencrypt Wget quiet Jun 14, 2017
mysql Import from tigase-kontalk repository Jun 7, 2017
tigase Use tigase-kontalk repository as the version pointer (close #10) Jan 10, 2018
.gitignore Branch selection on build and store it into .version Jun 11, 2017
README.md README: Help and support Sep 24, 2017
kontalk-setup Minor clarity fixes Oct 8, 2018
launcher More or less complete backup/restore procedure (close #2) Oct 13, 2018
local.properties.dist Simple backup solution (WIP; #2) Oct 8, 2018


Kontalk server for Docker

Here you may find a few scripts and files to build a Kontalk container (actually 3 containers) for running a Kontalk server.


  • Recent 64-bit Linux distro (we suggest Debian)
  • Docker
  • Docker Compose
  • git

Setting up environment

Setup a new user account (or use an existing one, root is not needed and not recommended) on a system with Docker installed and enabled. The user account should be part of the docker group so it will be able to use Docker.

Clone this repository in any location (we recommend the home directory of your user account):

git clone https://github.com/kontalk/xmppserver-docker.git kontalk-server
cd kontalk-server

Configure the containers

A setup script can be used to generate a local configuration:


Answer all questions or skip them by pressing enter: the default value will be used (unless specified otherwise).

Please give a name to your new Kontalk server instance.
Kontalk instance name [prime]:

Kontalk is available in the following branches:
  master: bleeding-edge, latest modifications. Possibly unstable. Use for development only.
  staging: used in Kontalk test server. It should have the latest features with a certain degree of stability.
  production: used in Kontalk production server. Stable and tested.
You can also specify a version tag.

Kontalk version/branch to build [staging]:
XMPP service name [prime.kontalk.net]:
XMPP plain listen port [5222]:
XMPP secure listen port [5223]:
XMPP s2s listen port [5269]:
MySQL root password [root]:
MySQL kontalk password [kontalk]:
MySQL time zone [Europe/Rome]:

The HTTP file upload service is used by clients to upload and download media.
It should be exposed directly or better through a reverse proxy (e.g. Nginx).
We will ask you for the listen port exposed to the host system and the URLs seen by clients.
Note that those URLs should be available from the outside, i.e. from the Internet

HTTP file upload service listen port [8828]:
HTTP file upload URL []:
HTTP file download URL []:
Max HTTP upload file size [20971520]:

You can now build the images by running ./launcher bootstrap

A file called local.properties will be created. Please note that any modification to this file will require a rebuild (see below). If all went ok, you can now do the bootstrap:

./launcher bootstrap

This should take some time: it will build the images and setup the containers.

At this point, if you want to just run a development server for tests, just go straight below to the actual startup.

Setting up the server

A more serious environment will require prior creation of a SSL certificate and a GPG key for the server. For the containers to use them, certificate and keys must be located in:

  • config/server-private.key: GPG server private key (must not be password-protected!)
  • config/server-public.key: GPG server public key
  • config/privatekey.pem: SSL private key
  • config/certificate.pem: SSL certificate
  • config/cachain.pem: SSL certificate authorities chain (optional)

Your setup will also surely include some tweaking on the server configuration. You can edit the default configuration file config/init.properties.in. The local server tutorial can be used to configure some of the parameters, e.g. registration providers or push notifications. A quick reference to Tigase parameters can be found here, while the administration guide is here. We strongly recommend giving it a look to know if the default configuration suits your needs.

When configuring Tigase init.properties.in file, leave placeholders for variables untouched (e.g. {{ .Env.FINGERPRINT }}): they will be replaced automatically.

Another file to look into would be config/tigase.conf. Some environment variables are defined, you should especially check JAVA_OPTIONS which contains the JVM parameters (heap memory, GC parameters, etc.). Note that despite the extension, it's a simple shell script file sourced by the server startup script, so bash syntax applies.

Start the containers

Run this command:

./launcher start

The script will start 3 containers in the background:

  • xmpp: the actual Tigase XMPP server
  • db: MySQL database server
  • httpupload: the HTTP upload component needed to upload media (pictures, audio files, etc.)

The actual container names will be prefixed with the instance name given to kontalk-setup. For example, if you typed "prime" as the instance name, containers will be called prime_xmpp, prime_db, prime_httpupload.

The instance name can be changed in local.properties (INSTANCE_NAME), but before doing that you must destroy the old containers (./launcher destroy), alter INSTANCE_NAME and then run ./launcher bootstrap.

The launcher script has some other useful commands that can be used. You can see a quick help by launching it without any arguments.

Upgrade/rebuild the containers

You must rebuild the containers if you:

  • modified local.properties (run ./launcher rebuild)
  • want to upgrade the Kontalk server (meaning modifying the VERSION property in local.properties)

You don't need to rebuild if you modify config/init.properties.in, but you will need to restart it:

./launcher restart

Help and support

You can ask for further information on how to deploy a Kontalk server and share your experiences on our community forum: https://forum.kontalk.org/c/support/server