Using Prosody with Docker

Docker is a tool that allows easy download of software images, which it can run in isolated "containers" on any system that has Docker installed.

Prosody has official images published in the main Docker registry. This makes Docker very useful for installing Prosody on systems without official Prosody packages, or for testing or developing Prosody without disturbing your main system.

The rest of this page assumes that you have Docker already installed on your system and working. If you do not currently have Docker, see the Docker installation guide.

Getting started

To launch the latest stable release of Prosody in a new container, run:

docker run -d --name prosody -p 5222:5222 prosody/prosody

The first time you run this, it may take some time to download the required Docker images.

The default configuration will serve "localhost", but you will want to override this. One way to do this is by mounting your configuration files inside the container. Let's say your configuration is at /opt/prosody/config on your machine. When starting the container, use the '-v' option to add this as a mounted volume inside the container at /etc/prosody:

docker run -d --name prosody -p 5222:5222 -v /opt/prosody/config:/etc/prosody:ro prosody/prosody

The ':ro' at the end of the volume configuration tells Docker that it should be read-only. Prosody never needs to write to its config file, so this is just some additional safety. See Volumes for other possible mounts you might want to configure.

Official docker images

Our build server that handles all our releases and nightly builds, also builds Docker images and publishes them to the registry at prosody/prosody.

When telling Docker which image to use when pulling or starting a container, use `prosody/prosody`. You can optionally add a specific tag to use, such as `prosody/prosody:trunk`. By default Docker uses the tag called 'latest', which will always be our latest stable release.

We have individual tags for stable releases, such as `0.9.7`, `0.9.8`. We also have tags for our active release branches (including stable and in-development) like `0.9`, `0.10` and `trunk`. Our per-branch tags are rebuilt nightly whenever a change is committed, just like our regular nightly builds.


Our build server uses the scripts and Dockerfile from the prosody-docker project. It uses the latest stable release of prosody-docker to build new images.


Docker lets you override paths in the default container image, as described earlier when discussing how to provide configuration files to the container. Volumes are important, as they are the primary way to feed data into your container, as well as making sure that data stored by Prosody is preserved when the container is stopped or destroyed.

This table lists some mount points (inside the container) that you may want to put volumes at.

Mount point Description
/etc/prosody Configuration files and certificates
/var/lib/prosody Prosody’s data directory (can be used even if using a database for storage)
/var/log/prosody Prosody’s logs (may be overridden/unnecessary depending on your logging configuration