Prosody Setup Guide

Prerequisites

This guide assumes you have familiarity with:

Deploying an XMPP server can be a very simple process, or more extensive, depending on how many adjacent services you want to add. If you want to set up a quick single-user instance just to talk with others and join in chats on other servers, it can be be done in about 5 minutes. If you want to setup something to host federated chatrooms (MUCs), a file upload service, and video/voice calling--then it'll take much longer. You can add/remove services at any later time.

As a preview, the simplest example of a server setup on Ubuntu in under 8 commands for just enough configuration to start interacting on other servers would be (as executed as root):

add-apt-repository -U https://packages.prosody.im/debian -c main
apt update
apt install prosody certbot
certbot -d example.com
echo "VirtualHost example.com" >> /etc/prosody/prosody.cfg.lua
prosodyctl --root cert import /etc/letsencrypt/live/
prosodyctl adduser admin@example.com #Type in a password for the account, as prompted
prosodyctl config check && service prosody reload

This guide is configurable. You can set what domain you want to use, and what first admin user to create, and it will update the rest of the guide of how to set it up that way.

First XMPP admin account:
@

In addition to setup a basic server, I want to be able to:
  • Host federated chatrooms
  • Host a file upload system for sending files to others

Introduction

This guide covers Prosody, which is a very quick option to deploy, and adequate for userbases of <200 users. For platforms intending on >1k users, options like ejabberd would be more ideal. There is a migration path available from Prosody to ejabberd, to allow communities to be able to grow to more scalable options when appropriate. This doesn't mean Prosody is 'inferior', just that it targets a different profile and can be a simple moddable solution to start out with.

This guide focuses on the easier setup that's possible in Prosody 0.12 and later, which a majority of guides don't cover yet. While most Linux distributions only offer 0.11, it's best to start on 0.12, to not have to later reconfigure some services from 0.11 to 0.12.

DNS Plan

It's important to have a plan of what domain/subdomains you'll be using, as each service requires a valid TLS certificate. An XMPP server must have a valid certificate signed for the domain-part of the XMPP address. For example, if the intended address for a user is to be bob@example.com, then the server needs a valid TLS certificate for example.com. If your primary domain is used for something else, you can instead use a subdomain, like 'talk' or 'chat', etc—which would then have addresses like bob@talk.example.com. The example provided below is just a suggestion, it doesn't have to be done exactly as presented. You can also configure additional components to different subdomain names.

$ORIGIN example.com. $TTL 3600 ; (This example omits the NS and SOA records, which is out-of-scope of this guide) example.com. IN A 12.34.56.78 example.com. IN AAAA 2600:12:34::5678 _xmpp-client._tcp.example.com. IN SRV 0 5 5222 example.com. ; XMPP client port _xmpp-server._tcp.example.com. IN SRV 0 5 5269 example.com. ; XMPP server-to-server port _xmpps-client._tcp.example.com. IN SRV 0 5 5223 example.com. ; TLS XMPP client port _xmpps-server._tcp.example.com. IN SRV 0 5 5270 example.com. ; TLS XMPP server-to-server port muc.example.com. IN CNAME example.com. ; Federated chatroom service upload.example.com. IN CNAME example.com. ; File upload service pub.example.com. IN CNAME example.com. ; PubSub/microblogging service

Alternative documentation on DNS is available at: https://prosody.im/doc/dns

Note: if you use Namecheap for DNS hosting, there is a known bug with their interface pertaining to SRV records, if you're trying to setup under a subdomain (as noted in the comments section): https://www.namecheap.com/support/knowledgebase/article.aspx/318/2237/can-i-add-an-srv-record-for-my-domain/

Package Installation

Debian

Since the current distribution packages only ship Prosody 0.11, even in Debian 11, you'll have to add the vendor's repo:

sudo apt install extrepo
sudo extrepo enable prosody
sudo apt update
sudo apt install prosody

Ubuntu

Since the current distribution packages only ship Prosody 0.11, even in Ubuntu 22.04, you'll have to add the vendor's repo:

sudo add-apt-repository -U https://packages.prosody.im/debian -c main
sudo apt update
sudo apt install prosody

RHEL 8+ (and AlmaLinux, Rocky, CentOS, etc)

The package is available via EPEL, including Prosody 0.12 since RHEL8 and later

dnf install epel-release
dnf install prosody

Gentoo

https://packages.gentoo.org/packages/net-im/prosody

It's recommended to enable the USE flags: icu idn ssl zlib
You may add any of the database options (sqlite, mysql, or postgres), if you intend to use a database for storage.

Prosody Configuration

In nearly all Linux distributions, the Prosody configuration resides within /etc/prosody/

The primary config file is at /etc/prosody/prosody.cfg.lua. As implied by the file extension, the config file is written in Lua. On Debian-derivative distros, there's optionally the /etc/prosody/conf.d/ folder for additional config files; it's recommended to store your virtual host configuration there instead (any filename with a .cfg.lua extension), as a package update could overwrite /etc/prosody/prosody.cfg.lua. When making changes to the config, use prosodyctl check config to validate the config. This significantly helps prevent service interruption due to a typo.

If /etc/prosody/prosody.cfg.lua doesn't exist, just make a copy of the prosody.cfg.lua.dist file in the same folder, with the copy named as prosody.cfg.lua 

cd /etc/prosody/
cp prosody.cfg.lua.dist prosody.cfg.lua

Open prosody.cfg.lua in a text editor (such as nano) to start editing the configuration, as guided in the following sections.

nano prosody.cfg.lua

Enumerate Admin Accounts

Within prosody.cfg.lua navigate to the line that looks like the following:

admins = { }

Add a string of the XMPP address of the admin account you'll be creating:

admins = { "admin@example.com" }

If adding more than one, separate each string with a comma:

admins = { "admin@example.com", "anotheruser@example.com" }

Module Management

Within prosody.cfg.lua navigate to section starting with:

modules_enabled = {

Each string within this curly-braces segment designates the name of a module to be loaded globally. A specific module can be 'disabled' just by commenting out the string within the modules_enabled = {} section, using two dashes (--). Likewise, it can be enabled by removing the leading two dashes, or just manually typing a new string in. If adding a module name to the list, don't forget that each string needs to be terminated with a semi-colon (e.g. "mimicking";) otherwise you'll have a Lua syntax error.

Here's a few optional modules you can enable (that aren't enabled by default), along with their function:

    mam
    Strongly recommended to enable. Allows users to save recent message history, in order to make use of an account on multiple devices simpler. If this is disabled, then some clients may end up with gaps in conversation history.
    turn_external
    Enable this if you're setting up voice/video calling for the service.
    bosh
    Very optional. Intended for older/limited webclients. WebSockets are a successor to this, and recommended to use instead, but both can be enabled.
    websocket
    Enable this to allow people to use web-based clients. If you have a web server installed on the same server, you may need additional configuration for reverse-proxying WebSocket connections to Prosody
    mimicking
    Enable to prevent users from registering account names that are too visually similar to other existing account names, such as 'homograph attack'.
    proxy56
    Not recommended, as the http_file_share module is recommended instead for a better user experience with file sharing and transfer. This is an older method of XMPP file transfer.
    s2s_bidi
    More efficient method for server-to-server connectivity. Just a bit new and may be a little bit experimental.
    tombstones
    Prevents users from re-registering under a deleted username. You can leave it disabled if you want usernames to be 'released' after deletion.
    watchregistrations
    Helpful for administrators to keep an eye on account creation activity. Sends a message to all administrators when an account is registered.

Documentation for core modules are available at: https://prosody.im/doc/modules/

For later reading, here's the community website for all the modules available for Prosody (some may require separate installation): https://modules.prosody.im/

Database Configuration (Optional)

If you want to use an SQL database for storage, just uncomment the storage = "sql" line, as well as the corresponding example (starting with sql =) that corresponds with the SQL database backend you want. You can split up the line for readability like so:

storage = "sql"

sql = {
	driver = "MySQL",
	database = "prosody",
	username = "prosody",
	password = "secret",
	host = "localhost"
}

Virtual Host config

The last part is configuring a virtual host for the domain you intend to use. Below is a complete example config file for the earlier options selected. If you're using a Debian derivative (or just want to split up your config), you can save the following example config as a newly created file at /etc/prosody/conf.d/example.com.cfg.lua or just add it at the end of /etc/prosody/prosody.cfg.lua

VirtualHost "example.com" Component "upload.example.com" "http_file_share" -- Docs at https://prosody.im/doc/modules/mod_http_file_share http_file_share_expires_after = 60 * 60 * 24 * 30 -- 1 month http_file_share_size_limit = 128 * 1024 * 1024 -- 128MiB http_file_share_daily_quota = 512 * 1024 * 1024 -- 512MiB Component "muc.example.com" "muc" -- Docs at https://prosody.im/doc/modules/mod_muc restrict_room_creation = "local"

Indentation is provided for readability only. Any configuration that comes after a VirtualHost declaration will only apply to that virtual host, and likewise for Component sections.

You can validate your config with prosodyctl check config to check for any errors. If the configuration is fine, you may reload the service using service prosody reload

Next, you can create your first account via command line using:

prosodyctl adduser admin@example.com

It should ask for a password that you want to set; otherwise you can always reset the password with prosodyctl passwd admin@example.com

TLS Certificates

Before attempting to request TLS certificates, you can validate if DNS is set up correctly and is fully propagated by using prosodyctl check dns.

nginx and Certbot

Certbot standalone

((TODO))

After you have valid TLS certificates issued via certbot, you can import the keys and certificates using:

prosodyctl --root cert import /etc/letsencrypt/live/

It should report which certificates it found, and any misses. If all the necessary certificates are imported, you can simply reload the service to load the new certificates.

service prosody reload

At this point, you should be ready to start using your server.

This guide is mostly complete, but some sections aren't finished yet for setting up optional features: