Deploying Tigase

Introduction

Tigase is a powerful, open-source XMPP (Extensible Messaging and Presence Protocol) server designed for high-performance real-time communication. Built in Java, Tigase supports millions of concurrent connections and provides enterprise-grade features for building chat applications, IoT platforms, and real-time collaboration systems.

Key features of Tigase include:

• High Performance: Handle millions of concurrent XMPP connections
• Clustering Support: Horizontal scaling across multiple nodes
• Multi-Protocol: XMPP, WebSocket, BOSH (HTTP binding)
• End-to-End Encryption: OMEMO and OTR encryption support
• Multi-User Chat: Group chat rooms with full XEP support
• Push Notifications: Mobile push notification support (iOS/Android)
• File Transfer: HTTP file upload and transfer
• Message Archive: Store and retrieve message history
• PubSub: Publish-subscribe messaging patterns
• External Integrations: REST API and external authentication
• Modular Architecture: Extend with custom plugins

This guide walks you through deploying Tigase XMPP Server on Klutch.sh, configuring the database, and connecting XMPP clients.

Why Deploy Tigase on Klutch.sh

Deploying Tigase on Klutch.sh offers several advantages:

Always-On Messaging: Real-time communication requires constant availability. Klutch.sh ensures your XMPP server remains accessible 24/7.

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on your messaging application rather than infrastructure.

Scalable Resources: Start with modest resources and scale as your user base grows.

Persistent Storage: Message archives and user data persist across container restarts.

HTTPS by Default: Secure web administration and BOSH/WebSocket connections with automatic SSL.

Prerequisites

Before deploying Tigase 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 database server (MySQL/PostgreSQL/MongoDB)
• A domain for your XMPP server

Understanding XMPP Architecture

XMPP provides federated real-time messaging:

JID (Jabber ID): User addresses in format user@domain.com

Presence: Online status and availability information

Messages: One-to-one and group messaging

IQ (Info/Query): Request-response interactions

Roster: Contact lists and subscriptions

Preparing Your Repository

Create a GitHub repository with the following structure:

tigase-deploy/
├── Dockerfile
├── .dockerignore
└── config/
    └── config.tdsl

Creating the Dockerfile

FROM tigase/tigase-xmpp-server:latest

# Copy custom configuration
COPY config/config.tdsl /home/tigase/tigase-server/etc/config.tdsl

# Environment variables
ENV ADMIN_JID=${ADMIN_JID}
ENV ADMIN_PASSWORD=${ADMIN_PASSWORD}
ENV DB_TYPE=${DB_TYPE:-mysql}
ENV DB_HOST=${DB_HOST}
ENV DB_NAME=${DB_NAME:-tigasedb}
ENV DB_USER=${DB_USER}
ENV DB_PASS=${DB_PASS}

# Expose XMPP ports
EXPOSE 5222 5223 5269 5280 5290 8080

# The base image includes the default entrypoint

Configuration File

Create config/config.tdsl:

# Tigase XMPP Server Configuration

# Admin credentials
admins = [ 'admin@your-domain.com' ]

# Virtual hosts
'virtual-hosts' = [ 'your-domain.com' ]

# Database configuration
dataSource {
    default () {
        uri = 'jdbc:mysql://${DB_HOST}/${DB_NAME}?user=${DB_USER}&password=${DB_PASS}'
    }
}

# Client-to-server connections
c2s {
    connections {
        ports = [ 5222, 5223 ]
        '5223' {
            socket = ssl
        }
    }
}

# Server-to-server connections
s2s {
    connections {
        ports = [ 5269 ]
    }
}

# BOSH (HTTP binding)
bosh {
    connections {
        ports = [ 5280 ]
    }
}

# WebSocket
ws2s {
    connections {
        ports = [ 5290 ]
    }
}

# HTTP API
http {
    connections {
        ports = [ 8080 ]
    }
}

# Message archiving
'message-archive' () {}

# Multi-user chat
muc () {
    'muc-log' () {}
}

# Push notifications
'push' () {}

# File upload
upload () {}

Environment Variables Reference

Variable	Required	Default	Description
ADMIN_JID	Yes	-	Administrator JID (user@domain)
ADMIN_PASSWORD	Yes	-	Administrator password
DB_TYPE	No	mysql	Database type (mysql, postgresql, mongodb)
DB_HOST	Yes	-	Database hostname
DB_NAME	No	tigasedb	Database name
DB_USER	Yes	-	Database username
DB_PASS	Yes	-	Database password

Deploying on Klutch.sh

Set Up Database

Tigase requires a database. Deploy MySQL or PostgreSQL on Klutch.sh:

Mount Path	Size	Purpose
/var/lib/mysql	20 GB	Database storage

Create the Tigase database and user.

Configure DNS Records

Set up DNS records for your XMPP domain:

• A record: xmpp.yourdomain.com pointing to your server
• SRV records for client and server discovery

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “tigase” or “xmpp-server”.

Create the Tigase App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

For the web admin interface:

• Traffic type: HTTP
• Internal port: 8080

Note: XMPP client connections (5222, 5269) require TCP configuration.

Set Environment Variables

Configure the required variables:

Variable	Value
ADMIN_JID	admin@your-domain.com
ADMIN_PASSWORD	Your secure password
DB_HOST	Your database host
DB_NAME	tigasedb
DB_USER	Your database user
DB_PASS	Your database password

Attach Persistent Volumes

Add persistent storage:

Mount Path	Size	Purpose
/home/tigase/tigase-server/certs	1 GB	SSL certificates
/home/tigase/tigase-server/logs	5 GB	Server logs
/home/tigase/tigase-server/upload	10 GB	File uploads

Deploy Your Application

Click Deploy to build and launch Tigase.

Initialize the Database

Run the database schema installer on first deployment.

Initial Configuration

Accessing the Admin Panel

Access the web admin at https://your-app-name.klutch.sh:

1. Log in with your admin credentials
2. Navigate through the configuration options
3. Monitor server status and connections

Creating Users

Add users through the admin interface or command line:

1. Navigate to Users section
2. Click Add User
3. Enter JID and password
4. Configure user properties

Configuring Virtual Hosts

Add additional domains:

1. Go to Virtual Hosts configuration
2. Add new domain
3. Configure domain-specific settings
4. Update DNS records

Client Connections

Supported Clients

Popular XMPP clients:

• Desktop: Gajim, Dino, Swift, Pidgin
• Mobile: Conversations (Android), Siskin (iOS), Monal
• Web: Converse.js, JSXC

Client Configuration

Configure clients with:

• Server: your-domain.com
• Port: 5222 (or 5223 for SSL)
• JID: user@your-domain.com
• Password: User’s password

WebSocket and BOSH

For web clients:

• BOSH endpoint: https://your-server/bosh
• WebSocket: wss://your-server/ws2s

Advanced Features

Multi-User Chat (MUC)

Configure group chat rooms:

1. Enable MUC component
2. Create rooms through client or admin
3. Configure room settings (persistent, moderated, etc.)

Message Archive Management (MAM)

Store and retrieve message history:

# Enable in config.tdsl
'message-archive' () {
    'msg-archive-enabled' = true
}

Push Notifications

Configure mobile push:

1. Set up push notification service
2. Configure Tigase push component
3. Register mobile clients

File Upload

Enable HTTP file upload:

upload () {
    'upload-dir' = '/home/tigase/tigase-server/upload'
    'max-file-size' = 10485760  # 10 MB
}

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce strong passwords for all accounts
• TLS Everywhere: Enable TLS for all connections
• Certificate Management: Use valid SSL certificates
• Rate Limiting: Configure connection rate limits
• Access Control: Restrict admin access

Performance Optimization

• Connection Pooling: Optimize database connection pools
• Memory Settings: Tune JVM heap size
• Clustering: Deploy multiple nodes for high availability
• Monitoring: Track connection counts and resource usage

Backup Strategy

Protect your messaging data:

1. Regular database backups
2. Back up server certificates
3. Export user data periodically
4. Document configuration

Troubleshooting

Clients Cannot Connect

• Verify server is running and listening
• Check firewall/port configuration
• Verify DNS records
• Review TLS certificate validity

Authentication Failures

• Check database connectivity
• Verify user credentials
• Review authentication logs
• Check SASL mechanism configuration

Federation Not Working

• Verify S2S ports are open
• Check DNS SRV records
• Review S2S certificates
• Check server-to-server logs

High Memory Usage

• Tune JVM heap settings
• Review active connection count
• Check for memory leaks in plugins
• Consider clustering for distribution

Additional Resources

• Tigase Documentation
• Tigase GitHub Repository
• XMPP Extension Protocols (XEPs)
• Tigase Community
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Tigase on Klutch.sh provides a robust foundation for real-time messaging applications. With enterprise-grade features, high performance, and extensive protocol support, Tigase can power everything from simple chat applications to complex IoT communication platforms. The combination of Tigase’s powerful XMPP implementation and Klutch.sh’s reliable infrastructure ensures your messaging service remains fast, secure, and always available.