Public | Automated Build

Last pushed: 5 days ago
Short Description
Prosody XMPP server based on official package repository with Community Modules and telnet console
Full Description


Docker image building system for the Prosody XMPP server with Community Modules and telnet console.
This project was inspired by the official Prosody Docker and particularly to overcome this issue prosody/prosody-docker#29.


docker build --rm=true -t unclev/prosody-docker-extended .

It is available at Docker Hub.

The Docker Hub images are now re-builds within an hour after each nightly build in the official Prosody deb repository.

prosody-docker-extended features


The image exposes the following ports to the docker host:

  • 80: HTTP port
  • 443 HTTPS port
  • 5222: c2s port
  • 5269: s2s port
  • 5347: XMPP component port
  • 5280: BOSH / websocket port
  • 5281: Secure BOSH / websocket port

Note: These default ports can be changed in your configuration file. Therefore if you change these ports will not be exposed.


Volumes can be mounted at the following locations for adding in files:

  • /etc/prosody:
    • Prosody configuration file(s)
    • SSL certificates
    • Note: the starter copies the pre-configured at build time data into this location if it empty.
  • /var/lib/prosody:
    • Prosody internal data storage (see Data storage at the Prosody web site)
  • /var/log/prosody:
    • Log files for prosody - by default it is not used by prosody-docker-extended container, logs go to console and visible via docker logs.
    • Note: This location can be changed in the configuration, update to match
    • Also note: The log directory on the host (/logs/prosody in the example below) must be writeable by the prosody user
  • /usr/lib/prosody/modules-community:
  • /usr/lib/prosody/modules-custom:
    • Location for including additional modules
    • The image has the modules locations pre-configured as per installing_modules at the Prosody web site.
-- These paths are searched in the order specified, and before the default path
plugin_paths = { "/usr/lib/prosody/modules-custom", "/usr/lib/prosody/modules-community" }

Prosody user

There is a user with uid=1000(prosody) gid=1000(prosody) groups=1000(prosody) in the prosody-docker-extended image.

Adding a jabber user at startup

For compatibility with prosody/prosody-docker a user can be created by using environment variables LOCAL, DOMAIN, and PASSWORD. This performs the following action on startup:

prosodyctl register local domain password

Prosody will not check the user exists before running the command (i.e. existing users will be overwritten). It is expected that mod_admin_adhoc will then be in place for managing users (and the server).


docker run -d \
   --name prosody_xmpp_server \
   --hostname shakespeare.lit \
   -p 5222:5222 \
   -p 5269:5269 \
   -p localhost:5347:5347 \
   -e LOCAL=romeo \
   -e DOMAIN=shakespeare.lit \
   -e PASSWORD=juliet4ever \
   -v /srv/prosody/config:/etc/prosody \
   -v /srv/prosody/data:/var/lib/prosody \
   -v /srv/prosody/log:/var/log/prosody \
   -v /srv/prosody/modules/community:/usr/lib/prosody/modules-community \
   -v /srv/prosody/modules/custom:/usr/lib/prosody/modules-custom \

docker-compose.yml (v1) with PostgreSQL backend:

  image: postgres
  restart: always
  env_file: /srv/prosody/.env
    - '5432:5432'
    - '/srv/prosody/db/postgresql:/var/lib/postgresql/prosody'

  image: unclev/prosody-docker-extended:0.10
  restart: unless-stopped
  hostname: shakespeare.lit
    - 5222:5222
    - 5269:5269
    - 5347:5347
    - 5280:5280
  env_file: /srv/prosody/.env
    - sql:sql
    - '/srv/prosody/config:/etc/prosody'
    - '/srv/prosody/data:/var/lib/prosody'
    - '/srv/prosody/log:/var/log/prosody'
    - '/srv/prosody/modules/community:/usr/lib/prosody/modules-community'
    - '/srv/prosody/modules/custom:/usr/lib/prosody/modules-custom'

Starting the container shell

Connect to a linux shell of a running prosody-docker-extended container (or any other executable resides in the container) is easy:

docker exec -it prosody_xmpp_server bash

or with docker-compose

docker-compose exec xmpp_server bash

this brings linux shell with prosody user.

Explicitly specify --user root if you want root shell. See docker exec for more details.

Telnet console

prosody-docker-extended comes with telnet. Enabling mod_admin_telnet plugin (as of now it is not enabled by default) starts a telnet console to let you communicate with a running prosody server.

docker exec -it prosody_xmpp_server telnet localhost 5582

or with docker-compose

docker-compose exec xmpp_server telnet localhost 5582

For information on the telnet console see Console in the Prosody documentation.

It does not make sense requesting server:shutdown via the telnet console as in most configurations a container with the server restarts.


Using prosodyctl to control the server is aslo possible.
See the Prosody documentation: prosodyctl.

It does not make sense requesting start, stop, restart commands of prosodyctl, as prosody process is not started as a daemon within a container.

Note: do not change the pre-defined

daemonize = false;

setting in the prosody.cfg.lua.

To restart the server you can stop, remove, and re-start the container itself. For example, the only prosody_xmpp_server_1 container with docker-compose:

victor@unclev:/srv/prosody$ docker-compose stop xmpp_server && docker-compose rm -f xmpp_server && docker-compose up -d

or just

docker-compose down && docker-compose up -d

the last stops and re-starts all the services in the docker composition.

Community modules

For information on community modules address the Prosody documentation: community modules.

The prosody-docker-extended image comes with Mercurial SCM installed in it.
The container clones into /usr/lib/prosody/modules-community when it starts in the name of the prosody user.
Normally you should map /usr/lib/prosody/modules-community to a persistent location (on your docker host or a data container).

Even though the repository support within the image is very limited by (some modules may add files into their folders within the repo, which may prevent the repo from being updated). However, you can control community modules from the container shell.

victor@unclev:/srv/prosody$ docker-compose exec xmpp_server bash
prosody@unclev:/$ cd /usr/lib/prosody/modules-community   
prosody@unclev:/usr/lib/prosody/modules-community$ hg status
? mod_admin_web/admin_web/www_files/css/bootstrap-1.4.0.min.css
? mod_admin_web/admin_web/www_files/js/adhoc.js
? mod_admin_web/admin_web/www_files/js/jquery-1.10.2.min.js
? mod_admin_web/admin_web/www_files/js/strophe.min.js
? mod_mam_archive/
prosody@unclev:/usr/lib/prosody/modules-community$ hg pull --update
pulling from
searching for changes
no changes found

Custom modules

As a workaround you can put modules being used in your persistent location and map /usr/lib/prosody/modules-custom to it.

The prosody-docker-extended image is configured to look for modules under this location first.


The Prosody server within the prosody-docker-extended image is configured to log to "console" (see advanced_logging in the Prosody documentation).
This prevents contamination of the newly created container with such garbage.

Use mapping of /var/log/prosody directory want set up logs in a persistent location (likely - your docker host).

There is an example in Information for packagers - logging in the Prosody documentation.

log = {
        -- Log all error messages to prosody.err
        { levels = { min = "error" }, to = "file", filename = "/var/log/prosody/prosody.err" };
        -- Log everything of level "info" and higher (that is, all except "debug" messages)
        -- to prosody.log
        { levels = { min =  "info" }, to = "file", filename = "/var/log/prosody/prosody.log" };

Log rotation is supposed to be set up on your docker host. The prosody-docker-extended image itself does not support log rotation.

Configuring Prosody IM server

Configuring Prosody IM XMPP communication server resided within the prosody-docker-extended container is generally the same as configuring a standalone Prosody IM server,
but please don't forget specifying internal container paths, - not the external mapped paths, in the prosody config.
Please see the official Prosody IM documentation on configuring Prosody.

Docker Pull Command
Source Repository