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

An example command using docker to test launching Prosody in a new container:

docker run --rm --name prosody -p 5222:5222 prosodyim/prosody:13.0

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

For long-term use we recommend configuring and managing your container using another tool, such as docker compose. This allows you to easily modify the container’s configuration and update Prosody when needed. We provide an example docker-compose.yml for Prosody to get you started.

Download the file, edit it if necessary, and then run:

docker compose up -d

Re-run this command, in the same directory as your docker-compose.yml, any time you like to apply changes (you can add the --pull flag to also check for any updates and apply them).

prosodyctl

If you’re using the docker-compose.yml, you can run prosodyctl using:

docker compose exec prosody prosodyctl

For example, to access the runtime interactive shell:

docker compose exec prosody prosodyctl shell

Available images

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

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

Note: We previously published images to prosody/prosody but these are built from an older version of the dockerfile and are no longer maintained.

Dockerfile

Our build server uses the scripts and Dockerfile from the prosody-docker project. You can use this repository to build the container images yourself.

Volumes

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
/var/lib/prosody	Prosody’s data directory (can be used even if using a database for storage)
/etc/prosody	Configuration files and certificates
/var/log/prosody	Prosody’s logs (may be overridden/unnecessary depending on your logging configuration

The data directory defaults to /var/lib/prosody and in most cases you will want to mount a volume at this location, to make sure data is preserved (e.g. when updating the container). Some functionality may make use of this directory even if you use an alternative storage backend (such as SQL) as your primary data store.

The ownership of the data directory also determines the user that Prosody runs as (inside the container). Make sure the data directory is not owned by root, or the container will fail to start.

Mounting volumes at the other locations is optional.

Environment variables

If you do not provide your own config file mounted in /etc/prosody, the default configuration supports some environment variables to control the default behaviour.

Server

PROSODY_ADMINS: A comma-separated list of JIDs that should be admins of the Prosody instance.
PROSODY_LOGLEVEL: The minimum log level output. May be one of debug, info, warn or error. Defaults to info.

Hosts

PROSODY_VIRTUAL_HOSTS: Comma-separated list of virtual host names for Prosody to serve. If unset, it auto-detects the container hostname.
PROSODY_COMPONENTS: Comma-separated list of internal components. Each listed component should be of the form ADDRESS:MODULE - e.g. a MUC component might be groups.example.com:muc.
PROSODY_EXTERNAL_COMPONENTS: Comma-separated list of external components. Each listed component should be of the form ADDRESS:SECRET - e.g. gateway.example.com:my-secret-123.
PROSODY_NETWORK_HOSTNAME: Specifies the network address (not XMPP address) of the Prosody server. If set, this is used as the default HTTP host and proxy65 address. If a single virtual host is configured, the network hostname defaults to that.

Modules

PROSODY_PLUGIN_PATHS: A comma-separated list of paths to search for plugins (modules). Defaults to /etc/prosody/modules.
PROSODY_ENABLE_MODULES: A comma-separated list of modules to enable, in addition to those that are enabled by default.
PROSODY_DISABLE_MODULES: A comma-separated list of modules to disable.

Data retention

PROSODY_RETENTION_DAYS: The number of days to store data (messages, uploads, etc.) for. Setting this enables mod_mam.
PROSODY_ARCHIVE_EXPIRY_DAYS: The number of days to store messages for (e.g. for synchronization). Defaults to the value of PROSODY_RETENTION_DAYS, or 7 if that is not set either. Setting this enables mod_mam.
PROSODY_UPLOAD_EXPIRY_DAYS: The number of days to store file uploads for (so they can be fetched by recipients). Defaults to the value of PROSODY_RETENTION_DAYS, or 7 if that is not set.

Connections

PROSODY_CERTIFICATES: The path to the certificates directory, relative to the config directory. Defaults to certs (i.e. ‘/etc/prosody/certs’).
PROSODY_S2S_SECURE_AUTH: Whether to require valid certificates from other servers, or fall back to other methods such as dialback. Defaults to 1, set to 0 to enable dialback.
PROSODY_C2S_RATE_LIMIT: The default rate limit for client connections. Defaults to 10kb/s.
PROSODY_S2S_RATE_LIMIT: The default rate limit for server connections. Defaults to 30kb/s.

MUC

These settings are applied to any muc components. If none are defined, these settings will be ignored.

PROSODY_MUC_MODULES: A comma-separated list of modules to load on the MUC host, e.g. muc_mam.

Uploads

These settings are applied to any http_file_share components. If none are defined, these settings will be ignored.

PROSODY_UPLOAD_LIMIT_MB: The maximum file size in megabytes that Prosody will allow in a single share.
PROSODY_UPLOAD_STORAGE_GB: The total maximum storage that Prosody will use for uploads, for all users.

Storage

PROSODY_STORAGE: The name of the storage driver to use. Defaults to internal unless PROSODY_SQL_DRIVER is set, in which case it defaults to sql.
PROSODY_SQL_DRIVER: The name of the SQL driver to use. Must be one of sqlite, postgres or mysql.
PROSODY_SQL_DB: The name of the database to connect to (the filename if using SQLite).
PROSODY_SQL_USERNAME: The username to authenticate to the database server with.
PROSODY_SQL_PASSWORD: The password to authenticate to the database server with.
PROSODY_SQL_HOST: The hostname of the database server.

TURN

PROSODY_TURN_SECRET: The secret token shared with the TURN server to authenticate clients. TURN won’t be advertised if this is not set.
PROSODY_TURN_HOST: The network address of the TURN service. Defaults to Prosody’s hostname if not set.
PROSODY_TURN_PORT: The network port of the TURN service.
PROSODY_TURN_TLS_PORT: The network port for TURN over TLS (if any).

Other

PROSODY_STATISTICS: Enable Prosody’s statistics/metrics gathering. Disabled by default, but you may want to set it to internal.
PROSODY_EXTRA_CONFIG: An path/pattern to include after the main config (included files can add or override options). Defaults to /etc/prosody/conf.d/*.cfg.lua.