Deploying MongooseIM

Introduction

MongooseIM is a robust, scalable instant messaging server built on the XMPP/Jabber protocol. Developed by Erlang Solutions, it’s designed to handle millions of concurrent connections while maintaining high availability and fault tolerance. MongooseIM powers messaging infrastructure for enterprises, gaming platforms, and IoT applications worldwide.

Built with Erlang/OTP, MongooseIM inherits the renowned reliability and concurrency capabilities of the Erlang runtime. The server supports modern messaging features including push notifications, message archives, and group chat, while maintaining compatibility with the extensive XMPP ecosystem.

Key highlights of MongooseIM:

Massive Scalability: Handle millions of concurrent connections
XMPP Standard: Full compliance with XMPP protocols
Push Notifications: iOS and Android push support
Message Archive: Persistent message history with MAM
Multi-User Chat: Group messaging and chat rooms
Federation: Connect with other XMPP servers
Clustering: Horizontal scaling across nodes
REST API: Administrative and integration APIs
GraphQL API: Modern query interface
WebSocket Support: Real-time web connections
BOSH: HTTP binding for web clients
Metrics: Comprehensive monitoring with Prometheus
Extensible: Plugin architecture for customization
Open Source: Apache 2.0 licensed

This guide covers deploying MongooseIM on Klutch.sh, configuring for production, and managing your messaging infrastructure.

Why Deploy MongooseIM on Klutch.sh

Deploying MongooseIM on Klutch.sh provides significant advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys MongooseIM. Push to GitHub, and your messaging server deploys automatically.

Persistent Storage: Attach volumes for message archives, configurations, and databases.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure BOSH and WebSocket connections.

GitHub Integration: Connect your repository for automatic deployments on updates.

Scalable Resources: Allocate CPU and memory based on expected connection counts.

Environment Variable Management: Securely store database credentials and configuration.

Custom Domains: Use your own domain for XMPP server identity.

Always-On Availability: Your messaging server stays accessible 24/7.

Prerequisites

Before deploying MongooseIM on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and XMPP concepts
A domain for your XMPP server
Database backend (PostgreSQL, MySQL, or Mnesia)
(Optional) Push notification credentials (APNS/FCM)

Understanding MongooseIM Architecture

MongooseIM consists of several components:

Core Server: Erlang/OTP application handling XMPP logic.

Connection Listeners: Handle client connections (C2S, S2S, BOSH, WebSocket).

Session Manager: Tracks online users and sessions.

Router: Directs messages between users and components.

Database Backend: Stores users, messages, and configuration (PostgreSQL, MySQL, or Mnesia).

Extensions (XEPs): Protocol extensions for features like MAM, MUC, and push.

Preparing Your Repository

Repository Structure

mongooseim-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM mongooseim/mongooseim:latest

# Environment configuration
ENV MONGOOSEIM_HOST=${MONGOOSEIM_HOST}
ENV MONGOOSEIM_ADMIN_USER=${MONGOOSEIM_ADMIN_USER:-admin}
ENV MONGOOSEIM_ADMIN_PASSWORD=${MONGOOSEIM_ADMIN_PASSWORD}

# Database configuration
ENV MONGOOSEIM_DB_TYPE=${MONGOOSEIM_DB_TYPE:-pgsql}
ENV MONGOOSEIM_DB_HOST=${MONGOOSEIM_DB_HOST}
ENV MONGOOSEIM_DB_NAME=${MONGOOSEIM_DB_NAME}
ENV MONGOOSEIM_DB_USER=${MONGOOSEIM_DB_USER}
ENV MONGOOSEIM_DB_PASSWORD=${MONGOOSEIM_DB_PASSWORD}

# Create directories
RUN mkdir -p /var/lib/mongooseim /var/log/mongooseim

# Expose ports
# 5222 - Client to server
# 5269 - Server to server
# 5280 - HTTP (BOSH, WebSocket, API)
# 5285 - HTTPS
EXPOSE 5222 5269 5280 5285

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD mongooseimctl status || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`MONGOOSEIM_HOST`	Yes	-	Primary XMPP domain
`MONGOOSEIM_ADMIN_USER`	No	admin	Admin username
`MONGOOSEIM_ADMIN_PASSWORD`	Yes	-	Admin password
`MONGOOSEIM_DB_TYPE`	No	pgsql	Database type (pgsql, mysql, mnesia)
`MONGOOSEIM_DB_HOST`	Yes	-	Database host
`MONGOOSEIM_DB_NAME`	Yes	-	Database name
`MONGOOSEIM_DB_USER`	Yes	-	Database username
`MONGOOSEIM_DB_PASSWORD`	Yes	-	Database password

Deploying MongooseIM on Klutch.sh

Generate Admin Password

Create a secure admin password:

openssl rand -base64 24

Provision Database

Set up PostgreSQL or MySQL database for MongooseIM.

Configure DNS

Set up SRV records for XMPP discovery:

_xmpp-client._tcp.yourdomain.com SRV 0 5 5222 xmpp.yourdomain.com
_xmpp-server._tcp.yourdomain.com SRV 0 5 5269 xmpp.yourdomain.com

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial MongooseIM deployment"
git remote add origin https://github.com/yourusername/mongooseim-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “mongooseim” or “chat-server”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

In deployment settings:

Select HTTP as the traffic type
Set the internal port to 5280 for HTTP/WebSocket access

Set Environment Variables

Configure your environment:

Variable	Value
`MONGOOSEIM_HOST`	`yourdomain.com`
`MONGOOSEIM_ADMIN_USER`	`admin`
`MONGOOSEIM_ADMIN_PASSWORD`	Your secure password
`MONGOOSEIM_DB_TYPE`	`pgsql`
`MONGOOSEIM_DB_HOST`	Your PostgreSQL host
`MONGOOSEIM_DB_NAME`	`mongooseim`
`MONGOOSEIM_DB_USER`	Your database user
`MONGOOSEIM_DB_PASSWORD`	Your database password

Attach Persistent Volumes

Add volumes for persistent data:

Mount Path	Recommended Size	Purpose
`/var/lib/mongooseim`	50 GB	Data and Mnesia database
`/var/log/mongooseim`	5 GB	Log files

Deploy Your Application

Click Deploy to build and launch MongooseIM.

Register Admin User

After deployment, register the admin user:

mongooseimctl register admin yourdomain.com password

Access MongooseIM

Connect XMPP clients to your server.

User Management

Registering Users

Via command line:

mongooseimctl register username yourdomain.com password

Via REST API:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"user":"newuser","host":"yourdomain.com","password":"secret"}' \
  https://your-server:5285/api/users

In-Band Registration

Enable users to register via XMPP clients:

Configure mod_register in configuration
Set registration policies
Optionally add CAPTCHA

Deleting Users

mongooseimctl unregister username yourdomain.com

Message Archive (MAM)

Enabling MAM

Message Archive Management stores message history:

Configure mod_mam in settings
Set archive backend (database)
Configure retention policy

MAM Settings

default_result_limit: Maximum messages per query
max_result_limit: Hard limit on results
archive_chat_markers: Store read receipts

Multi-User Chat (MUC)

Configuring MUC

Enable group chat rooms:

Configure mod_muc module
Set default room options
Configure access controls

Room Types

Temporary: Deleted when empty
Persistent: Survive server restarts
Hidden: Not listed in directory

Room Administration

Create rooms programmatically:

mongooseimctl create_room room_name yourdomain.com

Push Notifications

Configuring Push

Enable mobile push notifications:

Configure mod_push_service module
Add APNS/FCM credentials
Set up push gateways

Apple Push (APNS)

{mod_push_service_mongoosepush, [
  {pool_name, apns},
  {api_version, "v3"}
]}

Firebase Cloud Messaging (FCM)

{mod_push_service_mongoosepush, [
  {pool_name, fcm}
]}

Monitoring

GraphQL API

Access comprehensive monitoring:

query {
  stat {
    globalStats {
      name
      value
    }
  }
}

Prometheus Metrics

Export metrics for Prometheus:

# HELP mongooseim_sessions_count Current sessions
mongooseim_sessions_count 1234

Health Checks

Monitor server status:

mongooseimctl status

Troubleshooting

Connection Failures

Verify DNS SRV records
Check TLS certificates
Review listener configuration

Authentication Issues

Verify user exists in database
Check password encoding
Review auth backend configuration

Performance Issues

Monitor connection counts
Check database performance
Review Erlang VM metrics

Federation Problems

Verify S2S listener is configured
Check DNS resolution
Review certificate chain

Additional Resources

Conclusion

MongooseIM on Klutch.sh provides enterprise-grade instant messaging with the scalability to handle millions of connections. The XMPP standard ensures interoperability with countless clients and servers, while features like MAM, MUC, and push notifications deliver a complete messaging experience. With Erlang’s renowned reliability and Klutch.sh’s deployment simplicity, you can run production messaging infrastructure without managing complex server setups.