Prosody (XMPP) on Pi

I saw at least 3 posts on Mastodon where people were asking how easy it is to install an XMPP server or what their choices are. Perhaps this might help somebody in a similar situation as mine.

I used to run ejabberd on my Pi and that stopped working for some reason so I shifted to Prosody and it’s working fine ever since. I am using a Raspberry Pi 3B+ which runs this blog, my gemlog and Prosody. All of this runs on Arch Linux arm. Here’s a minimal set up that can get your XMPP server up and running in no time. The installation and configuration steps are similar for any architecture.

  1. Install Prosody
    yay -S prosody
  2. Configure Prosody. The configuration file is located in /etc/prosody/prosody.cfg.lua. Open up the config file with your favorite text editor.

  3. Add the host. Uncomment the line which says VirtualHost "" and replace with your server name. This is what’s in my config.
    ----------- Virtual hosts -----------
    -- You need to add a VirtualHost entry for each domain you wish Prosody to serve.
    -- Settings under each VirtualHost entry apply *only* to that host.
    VirtualHost ""
  4. If you need to set up a chat room, uncomment this line in config file
    ---Set up a MUC (multi-user chat) room server on
     Component "" "muc"

    Modify the with your VirtualHost name. The chatroom server can be called anything else other than conference. Its just an example in the config file. For more details on how to configure the chatroom and DNS settings for the chatroom subdomain, dive in here and here.

  5. Save the config file and exit the text editor.

  6. Create a user. Replace <user> with your desired username and <VirtualHost> with what we added in the config file in the previous steps. Enter password when prompted.
    prosodyctl adduser <user>@<VirtualHost>

    Users can also be added with

    prosodyctl register <user> <VirtualHost> <password>
  7. Open up ports on your router for XMPP services. You need ports 5000, 5222, 5269, 5280, 5281 open at the least. More information on the required ports can be found here.

  8. SSL certificates! Place the SSL certificate for your XMPP server within the certs folder in /etc/prosody and Prosody will pick it up automatically. The location can be changed in the config file.
    -- Location of directory to find certificates in (relative to main config file):
     certificates = "certs"

    If you are using Let’s Encrypt for the certificates and already have one for the existing domain, simply import them into Prosody with this command in the terminal:

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

    certbot integrates with Prosody and can import the renewed certificate by adding a deploy-hook to certbot renew command.

    certbot renew --deploy-hook "prosodyctl --root cert import /etc/letsencrypt/live"

    Everything you need to know to use the certificates with XMPP server is here.

  9. Once everything is set up, enable and start the prosody service.
    sudo systemctl enable prosody
    sudo systemctl start prosody
  10. Now you can login with your preferred client from Desktop, browser or smartphone and chat with other users on different XMPP servers.

This is a very basic setup that will get your XMPP server up and running with OMEMO. For in-depth detail, please have a look into the official documentation. There are many modules available that can extend your XMPP experience.

update: Please note OMEMO is a client feature and one doesn’t need to do any set up on Prosody server for it to work. I haven’t had much success with OMEMO on Monal (iOS) but chatSecure was able to handle encrypted chat easily.

Day 74 - Join Me in #100DaysToOffload