Skip to content
Klutch.sh Docs

Deploying a Converse.js App

Introduction

Converse.js is a free and open-source XMPP chat client that runs directly in your web browser. Built with modern JavaScript and web technologies, it brings instant messaging capabilities to any website without requiring users to install dedicated applications. It’s designed to be lightweight, extensible, and user-friendly while maintaining full XMPP protocol compatibility.

XMPP (Extensible Messaging and Presence Protocol) is a battle-tested open standard for real-time communication. It powers many messaging systems, from corporate chat platforms to gaming services, and has been in use for over two decades.

What Makes Converse.js Special:

Web-Based: No installation required. Users simply access your website and start chatting immediately through their browser.

XMPP Compatible: Works with any XMPP server—whether that’s your own Prosody server or a hosted XMPP service. Full protocol support means zero vendor lock-in.

Highly Customizable: Deeply configurable through JavaScript, letting you customize appearance, behavior, and features to match your brand and requirements.

Modern JavaScript: Built with modern web standards, ES6, and responsive design. Works on desktop, tablet, and mobile browsers.

Extensible Architecture: Plugin system allows developers to add custom features and integrations without modifying core code.

Privacy Focused: Runs in the browser with optional end-to-end encryption support. No data stored on your servers beyond what XMPP protocol requires.

Real-Time Presence: Shows who’s online, typing indicators, message delivery receipts, and other presence features out of the box.

Multi-User Support: Supports direct messages, multi-person group chats, persistent chat rooms, and user management.

Converse.js is perfect for adding chat to your existing website or platform. Whether you’re building a support chat feature, team communication tool, or standalone messaging platform, Converse.js provides a flexible, standards-based solution that respects user privacy and data ownership.

This guide walks you through deploying Converse.js on Klutch.sh using Docker. You’ll learn how to configure the client with your XMPP server, customize the interface, implement security features, optimize performance, and troubleshoot common issues in production.

Prerequisites

Before deploying Converse.js to Klutch.sh, ensure you have:

  • A Klutch.sh account with dashboard access
  • A GitHub account for repository hosting
  • Docker installed locally for testing (optional but recommended)
  • Understanding of XMPP protocol and chat systems
  • An XMPP server to connect to (or plans to deploy one)
  • Basic knowledge of JavaScript configuration
  • Familiarity with web server concepts
  • A domain name for your chat interface (recommended)

Understanding Converse.js Architecture

Technology Stack

Converse.js is built on modern web technologies:

Frontend Framework:

  • Vanilla JavaScript (ES6+) with modular architecture
  • Strophe.js library for XMPP protocol communication
  • Backbone.js for application structure and events
  • HTML5 WebSockets for real-time bidirectional communication
  • CSS3 with responsive design

Dependencies:

  • Lodash for utility functions
  • Moment.js for date/time handling
  • Emojione for emoji support
  • Libsignal for end-to-end encryption (optional)

Build Tools:

  • Node.js for development and build processes
  • Webpack for bundling and optimization
  • Babel for JavaScript transpilation
  • LESS for stylesheet compilation

Server Components:

  • Node.js web server for serving the application
  • Proxy capabilities for XMPP HTTP binding
  • CORS handling for cross-origin requests
  • Static file serving for optimized assets

Core Components

User Interface: Responsive chat interface with message threads, user lists, and presence indicators

XMPP Connection: Handles connection to XMPP servers using WebSocket or HTTP binding

Message Handling: Sends, receives, and displays messages with delivery confirmation

Roster Management: Maintains user contact lists and availability status

Room Management: Supports multi-user chat rooms and group conversations

Presence Broadcasting: Shows online/offline status and typing indicators

File Transfer: Supports sharing files through XMPP protocol

Plugins: Extensible system for adding custom functionality

Installation and Setup

Step 1: Create Your Project Directory

Start with a dedicated directory for your Converse.js deployment:

Terminal window
mkdir conversejs-deployment
cd conversejs-deployment
git init

Step 2: Create Directory Structure

Set up the necessary directories for a production-ready deployment:

Terminal window
mkdir -p public config logs plugins

Your project structure will look like:

conversejs-deployment/
├── Dockerfile
├── docker-entrypoint.sh
├── converse.js.config.js
├── package.json
├── .dockerignore
├── .gitignore
├── public/
│   └── (static assets)
├── config/
│   └── (configuration files)
├── logs/
│   └── (application logs)
└── plugins/
    └── (custom plugins)

Step 3: Create package.json

Create package.json for your Node.js dependencies:

{
  "name": "conversejs-deployment",
  "version": "1.0.0",
  "description": "Converse.js deployment on Klutch.sh",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "node server.js",
    "build": "echo 'Build complete'"
  },
  "keywords": ["xmpp", "chat", "messaging"],
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.2",
    "converse.js": "^10.1.0",
    "dotenv": "^16.0.3",
    "helmet": "^7.0.0",
    "compression": "^1.7.4",
    "cors": "^2.8.5"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Step 4: Create Node.js Server

Create server.js to serve Converse.js:

const express = require('express');
const helmet = require('helmet');
const compression = require('compression');
const cors = require('cors');
const path = require('path');
require('dotenv').config();


const app = express();
const PORT = process.env.PORT || 3000;
const XMPP_SERVER = process.env.XMPP_SERVER || 'xmpp.example.com';
const XMPP_DOMAIN = process.env.XMPP_DOMAIN || 'example.com';


// Security middleware
app.use(helmet());
app.use(compression());
app.use(cors());


// Parse JSON
app.use(express.json());
app.use(express.urlencoded({ extended: true }));


// Serve static files
app.use(express.static(path.join(__dirname, 'public')));


// Serve Converse.js configuration
app.get('/config.js', (req, res) => {
  const config = `
    window.converseConfig = {
      auto_list_rooms: false,
      auto_login: false,
      allow_non_roster_messaging: false,
      show_controlbox_by_default: true,
      connection_options: {
        keepalive: true
      },
      debug: ${process.env.DEBUG === 'true' ? 'true' : 'false'},
      default_state: 'chatroom',
      discover_connection_methods: true,
      jid: '${XMPP_DOMAIN}',
      view_mode: 'fullscreen',
      muc_domain: 'conference.${XMPP_DOMAIN}',
      message_carbons: true,
      modtools_disable_query: false,
      play_sounds: true,
      sounds_path: '/sounds/',
      register_policy: 'open',
      roster_groups: true,
      show_chat_state_notifications: true,
      show_offline_users: false,
      synchronize_availability: true,
      theme: '${process.env.THEME || 'default'}',
      trusted_domain_whitelist: ['${XMPP_DOMAIN}'],
      websocket_url: 'wss://${XMPP_SERVER}:${process.env.XMPP_PORT || 5290}/ws',
      allow_bookmarks: true,
      allow_contact_requests: true,
      allow_logout: true,
      allow_muc_invitations: true
    };
  `;
  res.type('application/javascript');
  res.send(config);
});


// Health check endpoint
app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    xmpp_server: XMPP_SERVER,
    xmpp_domain: XMPP_DOMAIN
  });
});


// Serve main HTML
app.get('/', (req, res) => {
  res.sendFile(path.join(__dirname, 'public', 'index.html'));
});


// Error handling
app.use((err, req, res, next) => {
  console.error('Error:', err);
  res.status(500).json({
    error: 'Internal Server Error',
    message: process.env.DEBUG === 'true' ? err.message : 'An error occurred'
  });
});


// Start server
app.listen(PORT, () => {
  console.log(`Converse.js server running on port ${PORT}`);
  console.log(`XMPP Server: ${XMPP_SERVER}`);
  console.log(`XMPP Domain: ${XMPP_DOMAIN}`);
  console.log(`Environment: ${process.env.NODE_ENV || 'development'}`);
});


// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down gracefully');
  process.exit(0);
});

Step 5: Create HTML Template

Create public/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="XMPP Chat powered by Converse.js">
    <title>Chat - Converse.js</title>


    <!-- Converse.js CSS -->
    <link rel="stylesheet" type="text/css" media="screen"
          href="https://cdn.conversejs.org/dist/converse.min.css">


    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }


        html, body {
            height: 100%;
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        }


        body {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 100vh;
            padding: 20px;
        }


        #conversejs {
            width: 100%;
            max-width: 1200px;
            height: 600px;
            border-radius: 8px;
            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
            background: white;
        }


        .loader {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 100%;
            font-size: 18px;
            color: #666;
        }


        @media (max-width: 768px) {
            #conversejs {
                height: 100vh;
                max-width: 100%;
                border-radius: 0;
            }
        }
    </style>
</head>
<body>
    <div id="conversejs" class="loader">Loading chat interface...</div>


    <!-- Converse.js Library -->
    <script src="https://cdn.conversejs.org/dist/converse.min.js"
            integrity="sha384-..."
            crossorigin="anonymous"></script>


    <!-- Configuration -->
    <script src="/config.js"></script>


    <!-- Initialize -->
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            converse.initialize(window.converseConfig);


            // Log connection events
            converse.plugins.add('custom-plugin', {
                initialize: function() {
                    const _converse = this._converse;
                    _converse.api.listen.on('connected', function() {
                        console.log('Connected to XMPP server');
                    });
                    _converse.api.listen.on('disconnected', function() {
                        console.log('Disconnected from XMPP server');
                    });
                    _converse.api.listen.on('message', function(data) {
                        console.log('New message received');
                    });
                }
            });
        });
    </script>
</body>
</html>

Step 6: Create Dockerfile

Create a Dockerfile for production-ready deployment:

# Build stage
FROM node:18-alpine as builder


WORKDIR /app


# Copy package files
COPY package*.json ./


# Install dependencies
RUN npm ci --only=production


# Runtime stage
FROM node:18-alpine


# Install dumb-init for proper signal handling
RUN apk add --no-cache dumb-init


# Create app user
RUN addgroup -g 1000 node && \
    adduser -D -u 1000 -G node node


WORKDIR /app


# Copy from builder
COPY --from=builder --chown=node:node /app/node_modules ./node_modules


# Copy application files
COPY --chown=node:node package*.json ./
COPY --chown=node:node server.js ./
COPY --chown=node:node public/ ./public/


# Create logs directory
RUN mkdir -p logs && chown -R node:node logs


# Switch to non-root user
USER node


# Expose port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})" || exit 1


# Use dumb-init to handle signals
ENTRYPOINT ["dumb-init", "--"]


# Start application
CMD ["node", "server.js"]

Step 7: Create Environment Configuration

Create .env.example:

Terminal window
# Server configuration
NODE_ENV=production
PORT=3000
DEBUG=false


# XMPP Server configuration
XMPP_SERVER=xmpp.example.com
XMPP_DOMAIN=example.com
XMPP_PORT=5290


# UI Theme
THEME=default


# Optional: Allow anonymous login
ALLOW_ANONYMOUS=false


# Optional: Room settings
ALLOW_ROOM_CREATION=true
ROOM_DOMAIN=conference.example.com


# Optional: File upload
MAX_FILE_SIZE=10485760


# Optional: TLS configuration
TLS_ENABLED=true
TLS_CERT_PATH=/etc/ssl/certs/tls.crt
TLS_KEY_PATH=/etc/ssl/private/tls.key


# Optional: Custom branding
SITE_NAME="Chat"
SITE_DESCRIPTION="Real-time messaging powered by XMPP"

Step 8: Create .dockerignore

Create .dockerignore:

.git
.gitignore
.env
.env.local
.env.*.local
.DS_Store
node_modules
npm-debug.log
yarn-error.log
.vscode
.idea
README.md
docs/
tests/
coverage/
.eslintrc

Step 9: Create .gitignore

Create .gitignore:

# Environment
.env
.env.local
.env.*.local


# Dependencies
node_modules/
package-lock.json
yarn.lock


# Logs
logs/
*.log
npm-debug.log*


# Runtime
tmp/
temp/
.cache/


# IDE
.vscode/
.idea/
*.swp
*.swo


# OS
.DS_Store
Thumbs.db

Step 10: Commit to GitHub

Push your configuration to GitHub:

Terminal window
git add Dockerfile server.js public/ package.json .env.example .dockerignore .gitignore
git commit -m "Add Converse.js chat client Docker configuration for Klutch.sh deployment"
git branch -M main
git remote add origin https://github.com/yourusername/conversejs-deployment.git
git push -u origin main

Deploying to Klutch.sh

Now let’s deploy Converse.js to Klutch.sh with proper XMPP server integration.

Deployment Steps

  1. Access Klutch.sh Dashboard

    Navigate to klutch.sh/app and sign in with your GitHub account.

  2. Create a New Project

    In the Projects section, click “Create Project” and name it something like “Converse.js Chat” or “Team Messaging”.

  3. Create a New App

    Within your project, click “Create App” to begin configuring your Converse.js deployment.

  4. Connect Your Repository
    • Select GitHub as your Git source
    • Choose your repository with the Converse.js Dockerfile
    • Select the branch to deploy (typically main)

    Klutch.sh will automatically detect the Dockerfile in your repository root.

  5. Configure Traffic Settings
    • Traffic Type: Select HTTP (Converse.js runs as a web application)
    • Internal Port: Set to 3000 (Node.js default port)
  6. Configure Environment Variables

    Add the following environment variables to configure your Converse.js instance:

    XMPP Server Configuration:

    Terminal window
    # XMPP server hostname
    XMPP_SERVER=xmpp.example.com
    

    # XMPP domain
    XMPP_DOMAIN=example.com
    

    # XMPP WebSocket port
    XMPP_PORT=5290

    Application Configuration:

    Terminal window
    # Environment
    NODE_ENV=production
    

    # Debug mode
    DEBUG=false
    

    # Port configuration (internal)
    PORT=3000

    User Interface Configuration:

    Terminal window
    # Theme selection
    THEME=default
    

    # Site branding
    SITE_NAME="Your Chat Platform"
    SITE_DESCRIPTION="Real-time messaging powered by XMPP"
    

    # Feature flags
    ALLOW_ROOM_CREATION=true
    ALLOW_ANONYMOUS=false
    ALLOW_CONTACT_REQUESTS=true

    Room Configuration:

    Terminal window
    # Multi-user chat domain
    ROOM_DOMAIN=conference.example.com
    

    # Allow bookmarks
    ALLOW_BOOKMARKS=true
    

    # Allow MUC invitations
    ALLOW_MUC_INVITATIONS=true

    Security Note:

    • Verify XMPP server is accessible from Klutch.sh
    • Use secure WebSocket (WSS) connections when possible
    • Store sensitive XMPP credentials securely
    • Enable TLS on XMPP server
    • Keep XMPP_DOMAIN matching your server configuration
  7. Configure Compute Resources

    Choose appropriate resources based on expected concurrent users:

    Small Deployment (< 50 concurrent users):

    • CPU: 1 core
    • RAM: 512 MB
    • Suitable for: Small teams, internal communication

    Medium Deployment (50-200 concurrent users):

    • CPU: 1 core
    • RAM: 1 GB
    • Suitable for: Growing teams, community chat

    Large Deployment (200-500 concurrent users):

    • CPU: 2 cores
    • RAM: 2 GB
    • Suitable for: Large teams, public chat platforms

    Enterprise (500+ concurrent users):

    • CPU: 4 cores
    • RAM: 4 GB
    • Suitable for: Large organizations, high-traffic platforms

    You can scale based on actual usage patterns and performance monitoring.

  8. Deploy the Application

    Click “Create” to start the deployment. Klutch.sh will:

    1. Clone your repository
    2. Build the Docker image
    3. Configure environment variables
    4. Start the Converse.js Node.js server
    5. Assign a public URL (e.g., example-app.klutch.sh)
    6. Configure automatic HTTPS with SSL certificates

    Deployment typically takes 3-5 minutes.

  9. Monitor Deployment Progress

    Track the deployment:

    • Go to the Deployments tab
    • View real-time build and startup logs
    • Wait for status to show “Running”
    • Verify all environment variables are set correctly
  10. Test XMPP Connection

    After deployment, verify the XMPP connection:

    1. Navigate to your deployed URL: https://example-app.klutch.sh
    2. You should see the Converse.js chat interface
    3. The system should attempt to connect to your XMPP server
    4. Check browser console for any connection errors

    If you see connection errors:

    • Verify XMPP_SERVER is correct and reachable
    • Check XMPP_DOMAIN matches your server configuration
    • Ensure XMPP_PORT is correct (usually 5290 for WebSocket)
    • Verify XMPP server has WebSocket/BOSH enabled
    • Check firewall rules allow outbound WebSocket connections
  11. Configure Your Domain

    Add your custom domain to Klutch.sh:

    1. In Klutch.sh dashboard, go to Domains
    2. Click “Add Custom Domain”
    3. Enter your domain (e.g., chat.example.com)
    4. Update DNS with CNAME record pointing to example-app.klutch.sh
    5. Wait for DNS propagation and SSL certificate provisioning

    Update Converse.js Configuration:

    1. Update XMPP_DOMAIN if your chat domain differs from XMPP server
    2. Update room domain if needed: ROOM_DOMAIN=conference.your-domain.com
    3. Redeploy the application
  12. Verify Installation

    After deployment, verify everything is working:

    1. Frontend Access:

      Terminal window
      curl https://example-app.klutch.sh

      Should return HTML with chat interface.

    2. Health Check:

      Terminal window
      curl https://example-app.klutch.sh/health

      Should return JSON with healthy status and XMPP configuration.

    3. Configuration Access:

      Terminal window
      curl https://example-app.klutch.sh/config.js

      Should return JavaScript configuration object.

    4. XMPP Connection:

      • Open the chat interface in browser
      • Check browser console for connection status
      • Look for successful WebSocket connection
      • Test login with XMPP credentials

    5. Chat Functionality:

      • Log in with valid XMPP account
      • Join a chat room
      • Send a test message
      • Verify message delivery

XMPP Server Configuration

Converse.js requires an XMPP server to connect to. You can use an existing server or deploy one.

Prosody (Recommended for most deployments):

Prosody is lightweight, easy to configure, and perfect for running alongside Converse.js.

Terminal window
# Installation
apt-get install prosody


# Basic configuration
# Edit /etc/prosody/prosody.cfg.lua


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


Component "conference.example.com" "muc"
    restrict_room_creation = false

ejabberd:

A robust, scalable XMPP server suitable for large deployments.

Openfire:

Enterprise-grade XMPP server with web admin interface.

WebSocket/BOSH Configuration

For Converse.js to work, your XMPP server must support WebSocket or HTTP Binding (BOSH).

Enable WebSocket in Prosody:

Terminal window
modules_enabled = {
    -- ... other modules ...
    "websocket";  -- Enable WebSocket support
}


# In VirtualHost section:
consider_websocket_secure = true

Typical WebSocket URL:

Terminal window
wss://xmpp.example.com:5290/ws

XMPP Server Integration

From Converse.js Configuration:

{
    websocket_url: "wss://xmpp.example.com:5290/ws",
    bosh_service_url: "https://xmpp.example.com:5280/http-bind",
    jid: "example.com",
    muc_domain: "conference.example.com"
}

Choose either WebSocket OR BOSH based on your server setup. WebSocket is recommended for modern deployments.

Getting Started with Converse.js

User Login

Users access the chat interface through the browser:

  1. Navigate to your Converse.js URL
  2. Enter their XMPP username and password
  3. Click login
  4. Chat interface loads with their contacts

User Interface Features

Main Chat Area:

  • Display messages from conversations
  • Typing indicators showing who’s typing
  • Message delivery and read receipts
  • Emoji picker and formatting options

Roster (Contact List):

  • View all contacts and their status
  • See who’s online/offline
  • Start new conversations
  • Search contacts

Rooms:

  • Join multi-user chat rooms
  • Create new rooms
  • Invite others to rooms
  • Set room subject and description

Settings:

  • Change password
  • Manage notifications
  • Configure privacy settings
  • Customize interface theme

Creating and Joining Rooms

Multi-user chat rooms enable group conversations:

  1. Click “Join Room” or “Add Room”
  2. Enter room address: roomname@conference.example.com
  3. Choose to bookmark the room for quick access
  4. Click “Join”
  5. Invite other users to the room

Presence and Status

Show your availability to other users:

  • Available: Actively chatting
  • Away: Not at computer, but connection active
  • Do Not Disturb: Don’t want to be interrupted
  • Offline: Logged out

Set custom status messages to let people know what you’re doing.

Security Best Practices

User Authentication

Strong Passwords:

  • Enforce minimum 12 character passwords on XMPP server
  • Require mixed case, numbers, special characters
  • Encourage users to use unique passwords

Session Management:

  • Automatic timeout after period of inactivity
  • Clear sessions on logout
  • Prevent simultaneous logins from multiple devices (optional)

Transport Security

HTTPS:

  • Always use HTTPS for web interface (automatic with Klutch.sh)
  • All traffic encrypted in transit
  • Valid SSL certificates (automatic provisioning)

XMPP Connection Security:

  • Use WSS (WebSocket Secure) not WS
  • Enable TLS on XMPP server
  • Verify server certificate validity
  • Use secure connection strings

End-to-End Encryption

Converse.js supports OMEMO encryption for private messages:

{
    allow_message_corrections: true,
    allow_oob_transfer: false,
    message_carbons: true,
    omemo: {
        default: false  // Enable for specific rooms
    }
}

Data Privacy

Minimal Data Storage:

  • Converse.js runs client-side
  • Messages stored on XMPP server per protocol
  • No additional data stored on web server
  • XMPP server handles encryption policies

User Data:

  • Inform users their messages are stored by XMPP server
  • Provide data deletion mechanisms
  • Respect GDPR and privacy requirements
  • Document data retention policies

Access Control

Roster Visibility:

  • Users can control who sees them online
  • Manage subscription requests
  • Block unwanted users
  • Configure privacy lists

Room Permissions:

  • Set room access (open, members-only, password-protected)
  • Moderate room participation
  • Set role-based permissions
  • Configure who can send messages

Regular Updates

Keep components updated:

  1. Monitor Converse.js security advisories
  2. Update Node.js dependencies regularly
  3. Update XMPP server software
  4. Keep OS packages current
  5. Test updates in staging before production

Performance Optimization

Client-Side Performance

Asset Caching:

  • Browser caches static files
  • Converse.js minified and gzipped
  • Assets served from CDN when possible
  • Compression enabled at server level

JavaScript Optimization:

  • Tree shaking to remove unused code
  • Code splitting for lazy loading
  • Minimal bundle size for faster load

Server-Side Performance

Resource Allocation:

Terminal window
# Node.js memory limit
NODE_OPTIONS=--max-old-space-size=512

Connection Pooling:

  • Maintain persistent XMPP connections
  • Reuse WebSocket connections
  • Limit concurrent connections if needed

Network Optimization

WebSocket vs BOSH:

  • WebSocket: Modern, efficient, lower latency (recommended)
  • BOSH: Works in older browsers, more overhead

Message Batching:

  • Group multiple messages when possible
  • Reduce frequency of requests
  • Balance between latency and bandwidth

Monitoring

Key Metrics:

  • Server response time (< 200ms ideal)
  • WebSocket connection success rate
  • Active concurrent users
  • CPU and memory usage
  • Network bandwidth

Performance Alerts:

  • Alert if response time > 500ms
  • Alert if connection failure rate > 5%
  • Monitor resource usage trends

Troubleshooting

Issue 1: Cannot Connect to XMPP Server

Symptoms: WebSocket connection fails, “Connection refused” in console

Solutions:

  1. Verify XMPP Server Configuration:

    • Check XMPP_SERVER is correct

    • Verify server is running and accessible

    • Test connection from command line:

      Terminal window
      nc -zv xmpp.example.com 5290

  2. Check WebSocket Support:

    • Verify XMPP server has WebSocket enabled
    • Confirm correct WebSocket port (usually 5290)
    • Test WebSocket URL directly if possible

  3. DNS Resolution:

    • Verify DNS resolves XMPP server correctly
    • Check for firewall blocking DNS
    • Test: nslookup xmpp.example.com

  4. Firewall and Network:

    • Ensure port 5290 is open
    • Check for proxy/firewall blocking WebSocket
    • Test from different network if possible

Issue 2: Login Failures

Symptoms: Cannot log in with valid XMPP credentials

Solutions:

  1. Verify Credentials:

    • Confirm username and password are correct
    • Check account exists on XMPP server
    • Test login directly on XMPP server if possible

  2. Domain Configuration:

    • Verify XMPP_DOMAIN matches server
    • Check JID format (username@domain)
    • Confirm domain is configured on server

  3. XMPP Server Issues:

    • Check XMPP server logs for authentication errors
    • Verify user database is accessible
    • Check server certificate validity

  4. Browser Issues:

    • Clear browser cookies and cache
    • Try different browser
    • Check browser console for error details
    • Try private/incognito browsing

Issue 3: Slow Message Delivery

Symptoms: Messages take long time to send/receive

Solutions:

  1. Network Latency:

    • Check network speed
    • Measure RTT to XMPP server
    • Check for packet loss
    • Try different network if possible

  2. Server Performance:

    • Check XMPP server load
    • Monitor server CPU/memory
    • Review XMPP server logs
    • Increase server resources if needed

  3. Client Performance:

    • Monitor browser memory usage
    • Check CPU usage during chat
    • Look for long-running JavaScript
    • Upgrade client resources in Klutch.sh if needed

  4. Network Issues:

    • Check WebSocket connection is stable
    • Monitor for disconnections/reconnections
    • Check firewall throttling
    • Verify QoS settings not limiting traffic

Issue 4: Rooms Not Displaying

Symptoms: Cannot see or join chat rooms

Solutions:

  1. Room Configuration:

    • Verify ROOM_DOMAIN is correct
    • Check room name format
    • Ensure room exists on server
    • Verify user has permission to join

  2. MUC Component:

    • Verify MUC (Multi-User Chat) component is running
    • Check component is registered in XMPP server
    • Review server logs for errors
    • Test room creation directly on server

  3. Firewall/Access:

    • Check user not blocked from room
    • Verify user roster doesn’t block members
    • Check room access control settings
    • Verify server connection is active

Issue 5: File Upload Not Working

Symptoms: Cannot upload files, upload feature missing

Solutions:

  1. Configuration:

    • Enable file transfer in Converse.js config

    • Set reasonable file size limits:

      Terminal window
      MAX_FILE_SIZE=10485760  # 10MB

    • Check XMPP server supports file transfers

  2. Feature Support:

    • Verify XMPP server supports HTTP File Upload (XEP-0363)
    • Check component is loaded
    • Review server capabilities
    • Upgrade server if needed

  3. Browser Support:

    • Check browser supports File API
    • Verify no browser restrictions on uploads
    • Check browser console for errors
    • Try different browser

Issue 6: Certificate/SSL Errors

Symptoms: “Untrusted certificate”, “invalid certificate” errors

Solutions:

  1. XMPP Server Certificate:

    • Verify XMPP server has valid certificate
    • Check certificate is not expired
    • Verify certificate matches domain name
    • Check certificate chain is complete

  2. Browser Trust:

    • Clear browser SSL cache
    • Verify browser trusts CA that signed cert
    • Check for HSTS preload issues
    • Try different browser

  3. Mixed Content:

    • Ensure all resources loaded over HTTPS
    • Check no mixed HTTP/HTTPS content
    • Fix protocol mismatches in URLs

Issue 7: High Memory Usage

Symptoms: Application memory grows over time, becomes slow

Solutions:

  1. Browser Memory:

    • Close unnecessary browser tabs
    • Clear browser cache
    • Reload page periodically
    • Check for memory leaks in plugins

  2. Server Memory:

    • Monitor Node.js heap usage

    • Increase available memory:

      Terminal window
      NODE_OPTIONS=--max-old-space-size=1024

    • Restart application periodically

    • Profile for memory leaks

  3. Message History:

    • Limit message history loaded
    • Archive old messages
    • Limit conversation size
    • Implement message pagination

Issue 8: Deployment Failures

Symptoms: Deployment doesn’t complete, “Build failed” errors

Solutions:

  1. Check Build Logs:

    • Review Klutch.sh deployment logs
    • Look for specific error messages
    • Check npm install errors
    • Verify Dockerfile syntax

  2. Dependencies:

    • Ensure package.json is valid JSON
    • Verify all dependencies install successfully
    • Check for private repositories
    • Ensure sufficient disk space

  3. Environment Variables:

    • Verify XMPP_SERVER is set
    • Check all required env vars present
    • Ensure no special characters causing issues
    • Test configuration locally first

  4. Port Configuration:

    • Verify port 3000 is not conflicting
    • Check internal port configuration
    • Ensure no reserved ports used

Custom Domains

Using a custom domain makes your chat interface professional and branded.

Step 1: Add Domain in Klutch.sh

  1. Go to your Converse.js app in Klutch.sh dashboard
  2. Navigate to Domains
  3. Click “Add Custom Domain”
  4. Enter your domain (e.g., chat.example.com)
  5. Save

Step 2: Configure DNS

Update your domain provider DNS records:

Type: CNAME
Name: chat
Value: example-app.klutch.sh
TTL: 3600

Step 3: Update Configuration

Update environment variables if needed:

Terminal window
XMPP_DOMAIN=example.com
ROOM_DOMAIN=conference.example.com

Redeploy the application for changes to take effect.

Step 4: Verify Setup

  1. Wait for DNS propagation (up to 1 hour)

  2. Test domain resolution:

    Terminal window
    nslookup chat.example.com

  3. Verify HTTPS certificate is active

  4. Test chat interface loads on custom domain

Production Best Practices

Backup Strategy

What to Back Up:

  1. Converse.js configuration and customizations
  2. Custom plugins and modifications
  3. Application logs for audit trail

Note: Message data is stored on XMPP server, not Converse.js.

Backup Schedule:

  • Daily: Application configuration
  • Weekly: Custom code and plugins
  • Monthly: Full application state

Backup Commands:

Terminal window
# Backup configuration and code
tar -czf /backups/conversejs-$(date +%Y%m%d).tar.gz \
    server.js public/ config/


# Backup custom plugins if used
tar -czf /backups/conversejs-plugins-$(date +%Y%m%d).tar.gz plugins/

Monitoring and Logging

Key Metrics:

  • Server response time
  • WebSocket connection success rate
  • Active concurrent users
  • CPU and memory usage
  • Application error rate

Alerts:

  • Alert if response time > 500ms
  • Alert if memory > 80% capacity
  • Alert if CPU > 70% sustained
  • Alert if connection failure rate > 5%

Logging:

  • Application logs for debugging
  • XMPP server logs for connection issues
  • Browser console for client-side errors
  • Access logs for monitoring usage

Security Maintenance

Regular Tasks:

Daily:

  • Monitor error logs
  • Check application availability
  • Verify XMPP server connectivity

Weekly:

  • Update dependencies check
  • Security advisory monitoring
  • Review access logs

Monthly:

  • Full security audit
  • Dependency updates
  • Performance review
  • Backup verification

Quarterly:

  • Major updates testing
  • Security assessment
  • Capacity planning
  • Disaster recovery test

Scaling Strategies

When to Scale:

  • Response time increasing
  • Memory regularly > 80%
  • CPU > 70% sustained
  • Concurrent user limit approaching

Vertical Scaling:

  • Increase CPU cores
  • Increase RAM
  • Better network connection
  • Upgrade Klutch.sh resources

Horizontal Scaling (for very large deployments):

  • Multiple Converse.js instances
  • Load balancer distribution
  • Shared XMPP server backend
  • CDN for static assets

Additional Resources

Conclusion

You now have a production-ready Converse.js chat interface deployed on Klutch.sh. You’ve learned how to build a lightweight Node.js server that serves the Converse.js client, configure it to connect to your XMPP server, customize the interface for your needs, and implement security best practices.

Converse.js brings the power of XMPP—a proven, federated messaging protocol—to modern web browsers. Unlike proprietary chat platforms, XMPP gives you complete control over your messaging infrastructure. Your data stays on your servers, and users can interoperate with any other XMPP network.

The beauty of Converse.js is its flexibility. You can add it to an existing website, embed it in your application, or build a standalone chat platform. The customizable configuration lets you brand it, control features, and integrate with your workflow.

Klutch.sh handles the infrastructure complexity, so you can focus on building great user experiences. Automatic HTTPS, scalable resources, and simple deployment mean your chat platform is production-ready from day one.

Monitor your deployment’s performance, keep your XMPP server healthy, and update regularly. With proper maintenance, your Converse.js deployment will provide reliable, real-time communication for years to come.

For questions, check out the Converse.js documentation, XMPP standards, or Klutch.sh support. Happy chatting!