Deploying Spectrum 2

Introduction

Spectrum 2 is an open-source XMPP transport that acts as a gateway between XMPP (Jabber) servers and other messaging networks. It allows users of XMPP clients to communicate with people on networks like IRC, Slack, Telegram, Discord, and many others through a unified interface.

Built with C++ for performance and reliability, Spectrum 2 uses the libpurple library (the backend of Pidgin) to support dozens of protocols. This makes it one of the most versatile messaging gateways available.

Key highlights of Spectrum 2:

• Multi-Protocol Support: Connect to IRC, Slack, Telegram, Discord, Twitter, and more
• XMPP Transport: Standard XMPP component protocol for server integration
• libpurple Backend: Supports any protocol that Pidgin supports
• Gateway Mode: Run as a standalone gateway or server component
• User Isolation: Each user’s sessions are isolated for security
• Presence Bridging: Sync online status across networks
• Message History: Store and retrieve message history
• File Transfers: Support file transfers where protocols allow
• Multi-User Chat: Bridge group chats between networks
• Scalable: Handle many users with efficient resource usage
• Open Source: Licensed under GPLv2

This guide walks through deploying Spectrum 2 on Klutch.sh using Docker to create a messaging gateway for your XMPP server.

Why Deploy Spectrum 2 on Klutch.sh

Deploying Spectrum 2 on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the container build and deployment automatically.

Persistent Storage: User registrations and message history persist across restarts.

Secure Connections: HTTPS and secure XMPP connections with automatic certificates.

GitHub Integration: Version control your configuration and deploy updates automatically.

Scalable Resources: Allocate resources based on user count and traffic.

Environment Variable Management: Securely store API keys and credentials.

High Availability: Keep your messaging gateway running 24/7.

Network Isolation: Each deployment runs in its own isolated environment.

Prerequisites

Before deploying Spectrum 2 on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• An XMPP server (Prosody, ejabberd, etc.) to connect Spectrum 2 to
• API credentials for networks you want to bridge (Telegram, Discord, etc.)
• Basic familiarity with Docker and XMPP concepts

Deploying Spectrum 2 on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository for your Spectrum 2 deployment.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM ubuntu:22.04

# Install dependencies
RUN apt-get update && apt-get install -y \
    spectrum2 \
    libpurple0 \
    libpurple-dev \
    pidgin-data \
    libpurple-bin \
    purple-discord \
    purple-telegram \
    bitlbee-libpurple \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Create necessary directories
RUN mkdir -p /etc/spectrum2/transports \
    && mkdir -p /var/lib/spectrum2 \
    && mkdir -p /var/log/spectrum2

# Copy configuration
COPY spectrum2.cfg /etc/spectrum2/transports/

# Set permissions
RUN chown -R spectrum2:spectrum2 /var/lib/spectrum2 \
    && chown -R spectrum2:spectrum2 /var/log/spectrum2

# Expose XMPP component port
EXPOSE 5347

USER spectrum2

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD pgrep spectrum2 || exit 1

CMD ["spectrum2", "--config", "/etc/spectrum2/transports/spectrum2.cfg"]

Create Configuration File

Create spectrum2.cfg:

[service]
# The name of your transport
jid = gateway.your-xmpp-server.com

# XMPP server connection
server = your-xmpp-server.com
port = 5347
password = your_component_password

# Backend type (libpurple for multi-protocol)
backend = /usr/bin/spectrum2_libpurple_backend
backend_host = localhost
backend_port = 10000

# User settings
users_per_backend = 10
admins = admin@your-xmpp-server.com

# Logging
log_file = /var/log/spectrum2/spectrum2.log
logging = error

[registration]
enable_public_registration = true
require_local_account = false

[database]
type = sqlite3
database = /var/lib/spectrum2/database.db

[identity]
name = Messaging Gateway
type = gateway
category = gateway

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.

Create a New App

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

Configure TCP Traffic

In the deployment settings:

• Select TCP as the traffic type
• Set the internal port to 5347 (XMPP component port)

Set Environment Variables

Configure any needed environment variables:

Variable	Value
COMPONENT_SECRET	Shared secret with XMPP server
TELEGRAM_API_ID	Telegram API ID (if using Telegram)
TELEGRAM_API_HASH	Telegram API hash

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/lib/spectrum2	10 GB	User data and database
/var/log/spectrum2	5 GB	Application logs

Deploy Your Application

Click Deploy to build and start Spectrum 2.

Configure XMPP Server

Add Spectrum 2 as a component in your XMPP server configuration, using the deployed hostname and shared secret.

XMPP Server Configuration

Prosody Configuration

Add to your Prosody config:

Component "gateway.your-domain.com"
    component_secret = "your_component_password"

ejabberd Configuration

Add to your ejabberd.yml:

listen:
  -
    port: 5347
    module: ejabberd_service
    access: all
    hosts:
      "gateway.your-domain.com":
        password: "your_component_password"

Supported Protocols

Spectrum 2 with libpurple supports many protocols:

Protocol	Description
IRC	Internet Relay Chat networks
Telegram	Telegram messaging (requires API credentials)
Discord	Discord servers and DMs
Slack	Slack workspaces
Twitter	Twitter DMs (limited)
XMPP	Bridge between XMPP servers
Matrix	Matrix homeservers (via plugin)
Skype	Skype messaging (deprecated)

User Registration

Registering for a Gateway

Users register through their XMPP client:

1. Add the gateway JID (e.g., gateway.your-domain.com) as a contact
2. Follow the registration prompts
3. Enter credentials for the target network
4. The gateway connects to the remote network

Managing Registrations

Administrators can manage registrations:

1. View registered users in the database
2. Remove problematic registrations
3. Set per-user limits

Security Considerations

Credential Storage

• User credentials are stored in the database
• Consider encryption at rest for sensitive data
• Use secure connections between all components

Network Access

• Limit who can register for the gateway
• Monitor for abuse and spam
• Rate limit connection attempts

Troubleshooting

Users Cannot Connect

• Verify XMPP component configuration
• Check shared secret matches on both ends
• Review Spectrum 2 logs for errors

Protocol Not Working

• Ensure required plugins are installed
• Check API credentials are valid
• Verify network allows outbound connections

High Resource Usage

• Reduce users_per_backend setting
• Monitor memory usage
• Consider resource allocation adjustments

Additional Resources

• Spectrum 2 Official Site
• Spectrum 2 GitHub Repository
• Spectrum 2 Documentation
• Pidgin (libpurple)
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Spectrum 2 on Klutch.sh gives you a powerful messaging gateway that bridges XMPP with dozens of other networks. Users can communicate with contacts on IRC, Telegram, Discord, and more through their favorite XMPP client. With persistent storage, reliable uptime, and easy configuration, Spectrum 2 on Klutch.sh provides a solid foundation for unified messaging across disparate platforms.