Operating System Debian

How to Install and Configure Prosody XMPP Server on Debian 13

Install the Prosody XMPP server on Debian 13, add your domain and a chat-room service, import Let's Encrypt certificates, create users and run the self-checks.

Prosody is a lightweight XMPP (Jabber) server written in Lua. This guide installs it on Debian 13 (trixie), configures it for your own domain with a group-chat service, secures it with Let's Encrypt certificates, and creates the first accounts, so that users can sign in as name@example.com from any XMPP client. Differences for Debian 12 are noted where they exist. Debian 7 is long out of support, and the repository setup with apt-key that older tutorials show no longer works on current releases.

Requirements

  • A server running Debian 13 (or Debian 12) and a user with sudo rights.
  • DNS records pointing to the server for the XMPP domain, example.com, and for the chat-room subdomain, conference.example.com.
  • These TCP ports reachable from the internet: 5222 (client connections) and 5269 (server-to-server connections). Port 80 is needed briefly to obtain certificates.

If your server's host name differs from the domain in your addresses (the server is xmpp.example.com but users are name@example.com), publish SRV records so clients and other servers can find it:

_xmpp-client._tcp.example.com.   3600  IN  SRV  0  5  5222  xmpp.example.com.
_xmpp-server._tcp.example.com.   3600  IN  SRV  0  5  5269  xmpp.example.com.

The SRV target must be a name with an A or AAAA record, not a CNAME or an IP address.

Step 1: Install Prosody

Debian 13 ships Prosody 13.0 in its main repository:

sudo apt update
sudo apt install prosody

Debian 12 ships the older 0.12 series. To get 13.0 there, install it from bookworm-backports (sudo apt install -t bookworm-backports prosody) or use the project's own repository described below.

Optional: use the Prosody project repository

The distribution package receives security fixes but stays on the point release Debian froze. If you want each new upstream release, add the Prosody package repository, which supports Debian 12 and later, before installing:

sudo apt install wget lsb-release
sudo wget https://prosody.im/downloads/repos/$(lsb_release -sc)/prosody.sources -O/etc/apt/sources.list.d/prosody.sources
sudo apt update
sudo apt install prosody

Check what is installed at any time with:

sudo prosodyctl about

Step 2: Configure your domain

The configuration file is /etc/prosody/prosody.cfg.lua. Settings above the first VirtualHost line are global; settings below a VirtualHost or Component line apply only to that host. Open the file:

sudo nano /etc/prosody/prosody.cfg.lua

In the global section, set the administrator addresses:

admins = { "deploy@example.com" }

At the end of the file, in the virtual hosts section, add your domain and a multi-user chat (MUC) component for group chats:

VirtualHost "example.com"

Component "conference.example.com" "muc"

A VirtualHost is a domain that holds user accounts; Prosody needs at least one to start. Leave allow_registration at its default of false unless you really want anyone on the internet to create accounts on your server.

Step 3: Install TLS certificates

Prosody requires encryption for client and server connections by default, so both names need a valid certificate. Obtain one with Certbot (stop any web server on port 80 first, or use its web-server plugin instead of --standalone):

sudo apt install certbot
sudo certbot certonly --standalone -d example.com -d conference.example.com

Prosody does not run as root and cannot read the private keys under /etc/letsencrypt. Instead of loosening permissions, import the certificates into Prosody's own directory:

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

Make the import run automatically after every renewal by adding a deploy hook:

sudo tee /etc/letsencrypt/renewal-hooks/deploy/prosody.sh > /dev/null <<'EOF'
#!/bin/sh
/usr/bin/prosodyctl --root cert import /etc/letsencrypt/live
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/prosody.sh

Prosody locates imported certificates by domain name automatically, so no certificate paths need to be added to the configuration.

Step 4: Choose a storage backend (optional)

Out of the box Prosody stores accounts, rosters and messages in its internal file-based storage, which is fine for a small server and needs no setup. For larger installations you can switch to SQL. The Prosody documentation officially supports SQLite3 and PostgreSQL; MySQL and MariaDB may work but are not recommended by the project.

Install the Lua database driver for the backend you want (lua-dbi-sqlite3, lua-dbi-postgresql or lua-dbi-mysql):

sudo apt install lua-dbi-postgresql

Then set the storage options in the global section of prosody.cfg.lua. For a local PostgreSQL database named prosody:

storage = "sql"
sql = {
    driver = "PostgreSQL";
    database = "prosody";
    username = "prosody";
    password = "change-this-password";
}

If you do want MariaDB, create the database and user first:

sudo mariadb -e "CREATE DATABASE prosody CHARACTER SET utf8mb4; CREATE USER 'prosody'@'localhost' IDENTIFIED BY 'change-this-password'; GRANT ALL PRIVILEGES ON prosody.* TO 'prosody'@'localhost';"

and use driver = "MySQL"; (the name is case sensitive) together with host = "localhost"; in the sql block. Prosody creates and upgrades its tables itself, so the database user needs permission to create and alter tables. Decide on the backend before you create accounts: switching later means migrating the data.

Step 5: Check the configuration and start Prosody

Run the built-in configuration check, then restart the service so the new hosts are loaded:

sudo prosodyctl check config
sudo systemctl restart prosody
sudo systemctl status prosody

If a firewall is active, open the XMPP ports. With ufw, for example:

sudo ufw allow 5222/tcp
sudo ufw allow 5269/tcp

Step 6: Create user accounts

Create the administrator account you named in admins, and any other users. Prosody asks for the password interactively:

sudo prosodyctl adduser deploy@example.com

The related commands for day-to-day management are:

sudo prosodyctl passwd deploy@example.com
sudo prosodyctl deluser deploy@example.com

Step 7: Verify the setup

Prosody can test its own DNS records and certificates:

sudo prosodyctl check dns
sudo prosodyctl check certs

Fix anything these checks report, especially a missing certificate for conference.example.com. Then sign in from an XMPP client such as Conversations, Gajim or Dino with the address deploy@example.com and the password you set. To test federation, add a contact on another XMPP server and exchange a message.

Maintenance

  • After editing the configuration, run sudo prosodyctl check config and then sudo prosodyctl reload. Changes that add or remove hosts or modules generally need sudo systemctl restart prosody.
  • Logs are written to /var/log/prosody/prosody.log; service start-up problems also show in sudo journalctl -u prosody.
  • Prosody is updated with the rest of the system through sudo apt update && sudo apt upgrade.
  • sudo prosodyctl shell opens the administration console of the running server.

Frequently asked questions

Which ports does Prosody use besides 5222 and 5269?

Port 5281 serves HTTPS for features such as file upload and WebSocket, and 5000 is used by the optional file-transfer proxy. Ports 5280 (plain HTTP), 5347 (external components) and 5582 (console) listen only on the loopback interface by default and should not be opened to the internet.

How do I let other people create accounts without enabling open registration?

Create the accounts yourself with prosodyctl adduser, or enable Prosody's invitation module so that existing users or admins can hand out sign-up links. Open in-band registration (allow_registration = true) invites spam accounts and needs abuse handling.

Should I use MySQL or MariaDB for Prosody?

Only if you have a specific reason, such as an existing database server you must reuse. The project recommends SQLite3 or PostgreSQL for SQL storage, and the default internal storage is enough for small servers.

What changes on Debian 12?

Only the Prosody version: the main repository has the 0.12 series, while 13.0 is available from backports or the Prosody project repository. Configuration file location, prosodyctl commands and certificate import are the same.

Share story:

Continue reading other guides on How VPS.