Deploying Prosody IM

Introduction

Prosody IM is a lightweight, open-source XMPP (Jabber) server written in Lua. It’s designed to be easy to set up and configure while remaining flexible and extensible through its modular architecture. Prosody powers instant messaging, presence, and real-time communication for thousands of deployments worldwide.

XMPP (Extensible Messaging and Presence Protocol) is an open standard for messaging that supports federated communication between servers, much like email. This means users on your Prosody server can communicate with users on other XMPP servers across the internet.

Key highlights of Prosody IM:

• Lightweight: Minimal resource usage, suitable for small to large deployments
• Modular Architecture: Enable only the features you need through plugins
• Federation Support: Communicate with other XMPP servers worldwide
• Multi-User Chat: Create group chat rooms and channels
• End-to-End Encryption: Supports OMEMO and OTR encryption
• File Transfer: Share files securely through the server
• Mobile Push: Push notifications for mobile clients
• WebSocket Support: Web-based XMPP clients supported
• Standards Compliant: Full compliance with XMPP specifications
• Open Source: Licensed under MIT

This guide walks through deploying Prosody IM on Klutch.sh using Docker.

Why Deploy Prosody IM on Klutch.sh

Deploying Prosody IM on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Prosody without complex configuration.

Persistent Storage: Attach persistent volumes for user data, message archives, and configuration.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system.

Custom Domains: Use your own domain for professional XMPP identities.

Always-On Availability: Your messaging server remains operational 24/7 for reliable communication.

Prerequisites

Before deploying Prosody IM on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Prosody configuration
• A domain name with DNS access for XMPP records
• SSL certificates for your domain (or use Let’s Encrypt)
• Basic familiarity with XMPP concepts
• (Optional) An XMPP client for testing

Understanding XMPP Architecture

Prosody implements the XMPP protocol with several components:

Client Connections (c2s): Handles connections from XMPP clients on port 5222.

Server-to-Server (s2s): Enables federation with other XMPP servers on port 5269.

HTTP Services: Provides BOSH, WebSocket, and file upload on port 5280/5281.

Multi-User Chat (MUC): Group chat functionality on a subdomain.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and Prosody configuration.

Repository Structure

prosody-deploy/
├── Dockerfile
├── prosody.cfg.lua
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM prosody/prosody:latest

# Copy configuration
COPY prosody.cfg.lua /etc/prosody/prosody.cfg.lua

# Create data directories
RUN mkdir -p /var/lib/prosody /var/log/prosody \
    && chown -R prosody:prosody /var/lib/prosody /var/log/prosody

# Expose XMPP ports
EXPOSE 5222 5269 5280 5281

# Run as prosody user
USER prosody

CMD ["prosody"]

Creating prosody.cfg.lua Configuration

Create a prosody.cfg.lua file:

-- Prosody Configuration

-- Server identity
admins = { "admin@example.com" }

-- Network settings
interfaces = { "*" }
c2s_ports = { 5222 }
s2s_ports = { 5269 }
http_ports = { 5280 }
https_ports = { 5281 }

-- Modules to load
modules_enabled = {
    -- Required modules
    "roster";
    "saslauth";
    "tls";
    "dialback";
    "disco";

    -- Nice to have
    "carbons";
    "pep";
    "private";
    "blocklist";
    "vcard4";
    "vcard_legacy";

    -- Administration
    "admin_adhoc";

    -- HTTP modules
    "bosh";
    "websocket";
    "http_files";

    -- Multi-user chat
    "muc";
    "muc_mam";

    -- Message archive
    "mam";

    -- File upload
    "http_upload";

    -- Push notifications
    "cloud_notify";

    -- Modern features
    "smacks";
    "csi";
    "csi_simple";

    -- Server registration
    "register";
    "watchregistrations";
}

modules_disabled = {
    "s2s";  -- Disable if you don't want federation
}

-- Logging
log = {
    info = "/var/log/prosody/prosody.log";
    error = "/var/log/prosody/prosody.err";
}

-- Data storage
data_path = "/var/lib/prosody"
storage = "internal"

-- Archive settings
archive_expires_after = "1w"

-- TLS configuration
ssl = {
    key = "/etc/prosody/certs/example.com.key";
    certificate = "/etc/prosody/certs/example.com.crt";
}

-- Virtual hosts
VirtualHost "example.com"
    enabled = true

-- Multi-user chat component
Component "conference.example.com" "muc"
    name = "Chat Rooms"
    restrict_room_creation = false

-- HTTP upload component
Component "upload.example.com" "http_upload"
    http_upload_file_size_limit = 10*1024*1024
    http_upload_expire_after = 60*60*24*7

-- Authentication
authentication = "internal_hashed"

-- Registration
allow_registration = false

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying Prosody IM on Klutch.sh

Configure DNS Records

Set up DNS records for your XMPP server:

Record Type	Name	Value
A	xmpp.example.com	Your server IP
SRV	_xmpp-client._tcp.example.com	5 0 5222 xmpp.example.com
SRV	_xmpp-server._tcp.example.com	5 0 5269 xmpp.example.com
A	conference.example.com	Your server IP
A	upload.example.com	Your server IP

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile prosody.cfg.lua .dockerignore
git commit -m "Initial Prosody deployment configuration"
git remote add origin https://github.com/yourusername/prosody-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “prosody” or “xmpp-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Prosody Dockerfile.

Configure Traffic Settings

Configure the following ports:

• Port 5222 for client connections (XMPP c2s)
• Port 5269 for server federation (XMPP s2s)
• Port 5280 for HTTP/BOSH/WebSocket

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/lib/prosody	10 GB	User data and message archives
/var/log/prosody	1 GB	Log files
/etc/prosody/certs	100 MB	SSL certificates

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Prosody container

Create Admin Account

After deployment, create an admin account:

prosodyctl adduser admin@example.com

Connect with an XMPP Client

Use an XMPP client like Conversations (Android), Gajim (Desktop), or Siskin (iOS) to connect to your server.

Managing Users

Creating Users

prosodyctl adduser username@example.com

Changing Passwords

prosodyctl passwd username@example.com

Deleting Users

prosodyctl deluser username@example.com

Listing Users

prosodyctl mod_listusers

Multi-User Chat (MUC)

Creating Chat Rooms

Users can create rooms by joining a new room address like room@conference.example.com. Rooms can be configured as:

• Public: Listed in room directory
• Private: Unlisted and password-protected
• Persistent: Survives server restarts
• Members-Only: Requires invitation

Room Administration

Room owners can:

• Set room subject and description
• Configure access controls
• Manage member list
• Enable logging

Security Considerations

End-to-End Encryption

Enable client-side encryption with:

• OMEMO: Modern encryption standard (recommended)
• OTR: Off-the-Record messaging
• OpenPGP: GPG-based encryption

Server Security

• Keep Prosody updated to the latest version
• Use strong TLS configuration
• Disable registration if not needed
• Monitor for abuse

Troubleshooting Common Issues

Cannot Connect

Solutions:

• Verify DNS SRV records are correct
• Check firewall allows XMPP ports
• Verify TLS certificates are valid
• Review Prosody logs for errors

Federation Not Working

Solutions:

• Ensure s2s module is enabled
• Verify SRV records for server-to-server
• Check certificates include proper domain

Messages Not Delivering

Solutions:

• Check user exists on server
• Verify roster (contact list) permissions
• Review message archive settings

Additional Resources

• Prosody Official Website
• Prosody Documentation
• Prosody Community Modules
• XMPP Standards Foundation
• Klutch.sh Deployments

Conclusion

Deploying Prosody IM on Klutch.sh gives you a lightweight, powerful XMPP server for instant messaging and real-time communication. With support for federation, encryption, and modern messaging features, Prosody provides a complete messaging solution that you control.

Whether for personal use, team communication, or building federated messaging services, Prosody on Klutch.sh offers the reliability and flexibility needed for production messaging infrastructure.