← Back to home

[Prosody (outdated)]

This guide is for installing Prosody, an XMPP server that is decentralized, fast, simple and FOSS. The version we will be using is 0.11.12 and in the end the user will have a private and only c2s server. These options are of course changeable after or during the installation.


  • GNU/Linux system
  • VPS (recommended) or a home server
  • Domain name
  • Basic terminal knowledge


We install the main packages plus some extras for TLS encryption, A/V streaming, and file transfering. If you don’t care about these things you can skip them.

On Debian/Ubuntu:

apt install prosody prosody-modules python3-certbot-nginx coturn mercurial

prosody is the main package
prosody-modules are some extra packages for functionability
python3-certbot-nginx is for TLS encryption
coturn a STUN/TURN server that allows A/V streaming for users behind NAT
mercurial for installing community modules for the STUN/TURN server


The server’s CFG file is at /etc/prosody/prosody.cfg.lua.

Admin, users and the domain name

admins = { "admin1@domain.org", "admin2@domain.org" }
VirtualHost = "domain.org"

Now from the terminal add some users:

prosodyctl adduser user@domain.org

The program will prompt for a password. To delete a user use the command deluser, and for changing passwords use passwd, both with the JID as an option.

Modules enabled/disabled, user registration

Search for the line modules_enabled and add the modules http_files (file transfer), turn_external (STUN/TURN server) and uncomment csi_simple and disco if they are commented. Under modules_disabled only leave s2s uncommented. Finally, check if in the following lines allow_registration is set to false, which is self explanatory.

File transfering

We will be configuring two components in the CFG file. You should add them after the VirtualHost section.

Component "upload.domain.org" "http_upload"

Right after we add http_upload_file_size_limit = 20971520 and http_upload_expire_after = 60 * 60 * 24 * 7, for limiting the file size and setting its expiration.

Now, in the global section (before VirtualHost) add:

-- HTTP/HTTPS ports
http_ports = { 5280 }
http_interfaces = { "*", "::" }

https_ports = { 5281 }
https_interfaces = { "*", "::" }

If it is your case, remember to configure your firewall accordingly.

After VirtualHost we add:

disco_items = {
	{ "upload.domain.org", "File Sharing Service" },

In the components section:

Component "proxy.domain.org" "proxy65"
proxy65_address = "domain.org"

There is no need to add proxy65 to the modules_enabled list. This component lets users behind NAT transfer files.

Coturn: The STUN/TURN server

Check if coturn is running:

systemctl status coturn

If not start it:

systemctl enable --now coturn

Next thing to do is downloading and setting the correct modules from the community repository using mercurial.

hg clone https://hg.prosody.im/prosody-modules/ prosody-modules

Now you can either copy (not recommended) the modules mod_turn_external.lua and mod_external_services.lua to /usr/lib/prosody/modules or create another folder for the community plugins that will be installed and create symlinks for them. For the second option, add the created folder to the plugins path in prosody.cfg.lua:

plugins_path { "usr/lib/prosody/modules", "enabled/plugins/folder" } 

Create the symlinks from the community downloaded folder to your plugins enabled folder (it depends on where you downloaded those modules):

ln -s /downloadedfolder/mod_turn_external/mod_turn_external.lua /enabled/folder
ln -s /downloadedfolder/mod_external_services/mod_external_services.lua /enabled/folder

We edit the coturn cfg file that is located in /etc/turnserver.conf:


Finally uncomment use-auth-secret

We go back to our prosody.cfg.lua file. In the global section add:

turn_external_host = "turn.domain.org"
turn_external_secret = "yoursecretpassword"

VERY IMPORTANT: Certificates

We need to generate certificates for the domain and every subdomain we are using for our components. Also, we need to check for some configuration options that could be missing or commented.

First we generate:

certbot -d domain.org --nginx
certbot -d upload.domain.org --nginx
certbot -d proxy.domain.org --nginx
certbot -d turn.domain.org --nginx

The bot will give you some output in the terminal and prompt you for two options: select the second one every time.

Now, we need to import/install the certs to prosody:

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

The TLS encryption for the file transfering module needs to be explicitly configured, and for that we edit prosody.cfg.lua and add to global:

https_ssl = {
	certificate = "/etc/prosody/certs/upload.domain.org.crt";
	key = "/etc/prosody/certs/upload.domain.org.key";

Pay attention to the extension names and double check that you got the right path and files for each line.

Inside the same file, check the following line and set it to true:

c2s_require_encryption = true

We are done with our file transfering configuration.

For the STUN/TURN server we also need to modify its CFG file /etc/turnserver.conf to set a path for our certs:


Done. You can check for errors using prosodyctl check. As a final note, I should add that if you are using a VPS you probably have a firewall working. There are some ports that need to be forwarded: 5280, 5281, 5222, 5322, 5000, 3478. If you are not using a firewall I recommend you using ufw and start from there.

Also, that this configuration is very personal. You can add more components (for example multichat groups). For that you should RTFM, which is always ideal.