XMPP Server (Prosody)

Production-ready XMPP server with comprehensive features, extensive XEP compliance, and enterprise security.

Overview

Comprehensive Prosody XMPP server setup with both production and development configurations. Built from research of real-world XMPP deployments, this setup provides enterprise-level features with modern XMPP capabilities enabled by default.

Quick Start

Production Setup

# Clone repository
git clone https://github.com/allthingslinux/xmpp.atl.chat /opt/xmpp.atl.chat
cd /opt/xmpp.atl.chat

# Run setup with unified CLI
./prosody-manager setup

📢 New Unified CLI Available!
We've consolidated all scripts into a single prosody-manager CLI tool with better error handling, interactive modes, and integrated help. See the Migration Guide for details.

The setup process will:

Check dependencies (Docker, Docker Compose, OpenSSL)
Configure environment variables (.env file)
Set up Cloudflare API credentials
Generate wildcard SSL certificates
Set up automatic certificate renewal
Start all services
Create administrator user

Development Setup

# Clone and setup development environment
git clone https://github.com/allthingslinux/xmpp.atl.chat
cd xmpp.atl.chat

# Use unified CLI
./prosody-manager setup --dev

Development environment includes:

Full XMPP server with all modern features
PostgreSQL database with web admin interface
TURN/STUN server for voice/video calls
Development tools (log viewer, metrics, admin panel)
Test users automatically created
Self-signed certificates for localhost testing

Manual Setup

# Configure environment
cp examples/env.example .env
# Edit .env with your domain and database password

# Generate SSL certificate (Cloudflare DNS-01)
cp examples/cloudflare-credentials.ini.example cloudflare-credentials.ini
# Edit with your Cloudflare API token
docker compose --profile letsencrypt run --rm xmpp-certbot

# Set up certificate renewal
(crontab -l 2>/dev/null; echo "0 3 * * * cd /opt/xmpp.atl.chat && ./prosody-manager cert renew your-domain.com") | crontab -

# Deploy server
docker compose up -d xmpp-prosody xmpp-postgres

# Check status
docker compose logs -f xmpp-prosody

User Management

# Using unified CLI tool
./prosody-manager prosodyctl adduser [email protected]
./prosody-manager prosodyctl adduser [email protected]

# Or directly with Docker
docker compose exec xmpp-prosody prosodyctl adduser [email protected]

Connection Information

Production

Server: atl.chat
Ports: 5222 (STARTTLS), 5223 (Direct TLS)
Web Admin: https://xmpp.atl.chat:5281/admin
WebSocket: wss://xmpp.atl.chat:5281/xmpp-websocket

Development

Server: localhost
Domain: localhost
Ports: 5222 (STARTTLS), 5223 (Direct TLS)
Web Admin: http://localhost:5280/admin
Test Users: admin@localhost (admin123), alice@localhost (alice123), bob@localhost (bob123)

Features

Security (Default Enabled)

TLS 1.3 with perfect forward secrecy
SCRAM-SHA-256 authentication (XEP-0474)
Anti-spam and abuse protection with DNS blocklists
Certificate validation with DANE/TLSA support

Modern XMPP Features (Default Enabled)

Message Archive Management (MAM) - XEP-0313
Message Carbons - XEP-0280
Stream Management (SMACKS) - XEP-0198
Client State Indication (CSI) - XEP-0352
HTTP File Upload - XEP-0363
Push Notifications - XEP-0357

Mobile Optimizations (Default Enabled)

Battery-saving CSI configuration
Mobile presence deduplication
Optimized offline message handling
WebSocket and BOSH support

Professional Features (Default Enabled)

Multi-User Chat (MUC) - XEP-0045
Publish-Subscribe (PubSub) - XEP-0060
External Service Discovery - XEP-0215
TURN/STUN integration for voice/video calls
Web admin interface and monitoring

Service Architecture

Service	Purpose	Port(s)	Status
Prosody	XMPP server with PostgreSQL	5222, 5223, 5269, 5280, 5281	Core
PostgreSQL	Database backend	5432 (internal)	Core
Adminer	Database management interface	8080	Optional
Coturn	TURN/STUN server for voice/video	3478, 5349, 49152-65535	Optional

Deployment Options

# Minimal deployment (XMPP + Database only)
docker compose up -d xmpp-prosody xmpp-postgres

# With database management
docker compose up -d xmpp-prosody xmpp-postgres xmpp-adminer

# Full deployment (all services)
docker compose up -d

# Development environment
docker compose -f docker-compose.dev.yml up -d

Development Environment

Access URLs

Service	URL	Purpose
Development Dashboard	http://localhost:8081	Central hub with all links
Admin Panel	http://localhost:5280/admin	XMPP server management
Database Admin	http://localhost:8080	PostgreSQL web interface
Log Viewer	http://localhost:8082	Real-time log monitoring
Metrics	http://localhost:5280/metrics	Prometheus metrics

Development Tools

# Show environment status
./prosody-manager dev status

# Test all connectivity
./prosody-manager dev test

# Create more users
./prosody-manager dev adduser newuser password123

# View logs
./prosody-manager dev logs

# Show all URLs
./prosody-manager dev urls

# Complete cleanup (removes all data)
./prosody-manager dev cleanup

XEP Compliance

This server supports 50+ XMPP Extension Protocols (XEPs) for maximum client compatibility:

Category	Key XEPs	Status
Core Protocol	XEP-0030 (Service Discovery), XEP-0115 (Entity Capabilities)	✅
Modern Messaging	XEP-0313 (MAM), XEP-0280 (Carbons), XEP-0198 (Stream Management)	✅
File Sharing	XEP-0363 (HTTP Upload), XEP-0447 (Stateless File Sharing)	✅
Security	XEP-0384 (OMEMO), XEP-0474 (SASL SCRAM Downgrade Protection)	✅
Mobile	XEP-0352 (CSI), XEP-0357 (Push), XEP-0198 (Stream Management)	✅
Real-time	XEP-0215 (External Services), XEP-0167/0176 (Jingle A/V)	✅

View complete XEP compliance list

Security Features

Transport Security: TLS 1.3, perfect forward secrecy, modern cipher suites
Anti-Spam: DNS blocklists, rate limiting, JID reputation scoring
Authentication: Multi-factor auth support, SASL 2.0, SCRAM-SHA-256
Monitoring: Audit logging, security alerts, compliance reports
Network: IPv6 support, DNSSEC validation, SRV record discovery

View detailed security documentation

Management Tools

Database Management

Adminer provides a web-based database management interface:

# Start with database management
docker compose up -d xmpp-prosody xmpp-postgres xmpp-adminer

# Access Adminer at http://localhost:8080
# Login credentials are automatically configured from your .env file

Unified CLI Tool

The prosody-manager script provides comprehensive server management:

# Show all available commands
./prosody-manager help

# User management
./prosody-manager prosodyctl adduser [email protected]
./prosody-manager prosodyctl passwd [email protected]

# Health monitoring
./prosody-manager health all

# Certificate management
./prosody-manager cert check atl.chat
./prosody-manager cert install atl.chat

# Backup operations
./prosody-manager backup create
./prosody-manager backup restore backup.tar.gz

# Deployment management
./prosody-manager deploy up full

Documentation

For Users

Getting Started Guide - Detailed deployment walkthrough
Configuration Guide - Environment variables and settings

For Administrators

Administrator Guide - Essential admin documentation and CLI tool
DNS Setup - Required DNS records and security
Certificate Management - SSL/TLS certificates and Let's Encrypt
Security Hardening - Production security configuration

For Developers

Architecture Overview - System design and structure
Localhost Testing - Development environment guide
Prosody Modern Features - Advanced XMPP features

Reference

Module Reference - Complete module documentation
XEP Compliance - Supported XMPP extensions

Browse all documentation

Security Notice

Development environment is NOT secure:

Open registration enabled
Debug logging active
Self-signed certificates
Relaxed security settings

Never expose development environment to the internet! Use only for localhost testing.

Project Structure

xmpp.atl.chat/
├── prosody-manager          # Unified CLI management tool
├── core/                   # Core configuration files
│   ├── config/             # Single comprehensive Prosody configuration
│   └── database/           # Database initialization and migrations
├── web/                    # Web components and themes
│   ├── admin/              # Administrative web interfaces
│   ├── registration/       # User registration components
│   ├── webclient/          # Web-based XMPP client
│   └── assets/             # Static web assets
├── scripts/                # Essential system scripts
│   ├── setup/              # Docker entrypoint and module installation
│   ├── maintenance/        # Health check for Docker
│   └── migrate-to-cli.sh   # Migration helper (temporary)
├── deployment/             # Production deployment configurations
│   ├── reverse-proxy/      # nginx/Apache proxy configurations
│   ├── systemd/            # systemd service configurations
│   └── monitoring/         # Prometheus/Grafana configurations
├── templates/              # Configuration templates and examples
│   ├── env/                # Environment variable templates
│   ├── configs/            # Configuration file examples
│   └── deployment/         # Deployment configuration templates
├── docs/                   # Comprehensive documentation
│   ├── user/               # End-user guides (getting started, configuration)
│   ├── admin/              # Administrator guides (deployment, security)
│   ├── dev/                # Developer documentation (architecture, features)
│   └── reference/          # Technical reference (XEPs, modules, troubleshooting)
└── .runtime/               # Runtime data (certificates, logs, backups - gitignored)

Contributing

See docs/dev/architecture.md for development guidelines and project structure.

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
.github/workflows		.github/workflows
core		core
deployment		deployment
docs		docs
scripts		scripts
static-files		static-files
templates		templates
web		web
.editorconfig		.editorconfig
.gitignore		.gitignore
.hadolint.yaml		.hadolint.yaml
.luacheckrc		.luacheckrc
.markdownlint.yml		.markdownlint.yml
Dockerfile		Dockerfile
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
prosody-manager		prosody-manager
renovate.json		renovate.json

Uh oh!

allthingslinux/xmpp.atl.chat

Folders and files

Latest commit

History

Repository files navigation

XMPP Server (Prosody)

Overview

Quick Start

Production Setup

Development Setup

Manual Setup

User Management

Connection Information

Production

Development

Features

Security (Default Enabled)

Modern XMPP Features (Default Enabled)

Mobile Optimizations (Default Enabled)

Professional Features (Default Enabled)

Service Architecture

Deployment Options

Development Environment

Access URLs

Development Tools

XEP Compliance

Security Features

Management Tools

Database Management

Unified CLI Tool

Documentation

For Users

For Administrators

For Developers

Reference

Security Notice

Project Structure

Contributing

About

Topics

Resources

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors 2

Uh oh!

Languages

Packages