Deploying The Lounge

Introduction

The Lounge is a modern, self-hosted web IRC client designed to keep you connected. Unlike traditional IRC clients that disconnect when you close them, The Lounge maintains persistent connections to your IRC networks, ensuring you never miss a message. It provides a sleek, responsive web interface that works beautifully on desktop and mobile devices.

Key features of The Lounge include:

• Always Connected: Persistent connections to IRC networks, even when your browser is closed
• Modern Web Interface: Beautiful, responsive design that works on any device
• Push Notifications: Get notified of mentions and private messages on mobile
• Multi-User Support: Host a single instance for your entire team or community
• Message Synchronization: Messages sync across all your devices
• File Uploads: Share images and files directly in chat
• Link Previews: Automatic previews for shared URLs
• Theming Support: Customize the look with built-in and custom themes
• LDAP Integration: Connect to existing authentication systems
• Cross-Platform: Access from any browser on any operating system

This guide walks you through deploying The Lounge on Klutch.sh, configuring user accounts, and connecting to IRC networks.

Why Deploy The Lounge on Klutch.sh

Deploying The Lounge on Klutch.sh provides several advantages:

Persistent Connections: Your IRC connections remain active 24/7, logging messages even when you’re away, thanks to Klutch.sh’s always-on infrastructure.

HTTPS by Default: Automatic SSL certificates ensure secure access to your IRC client from anywhere.

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on chatting rather than managing servers.

Persistent Storage: Your message history, user settings, and configuration persist across deployments.

Access Anywhere: Connect to IRC from any device with a web browser, without installing client software.

GitHub Integration: Version control your configuration and enable automatic redeployments.

Prerequisites

Before deploying The Lounge on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• IRC networks you want to connect to
• Basic familiarity with Docker and IRC concepts

Understanding The Lounge Modes

The Lounge operates in different modes:

Private Mode: Each user has their own account with separate IRC connections and history. Best for teams and communities.

Public Mode: A single shared IRC connection that anyone can access. Useful for public demonstrations or simple setups.

This guide focuses on private mode for multi-user deployments.

Preparing Your Repository

Create a GitHub repository with the following structure:

thelounge-deploy/
├── Dockerfile
├── .dockerignore
└── config/
    └── config.js

Creating the Dockerfile

FROM thelounge/thelounge:latest

# Set environment variables
ENV THELOUNGE_HOME=/var/opt/thelounge

# Create configuration directory
RUN mkdir -p ${THELOUNGE_HOME}

# Copy custom configuration (optional)
COPY config/config.js ${THELOUNGE_HOME}/config.js

# Expose the web interface port
EXPOSE 9000

# The base image includes the default entrypoint

Configuration File

Create config/config.js:

"use strict";

module.exports = {
    // Public mode: false for private (user accounts), true for public
    public: false,

    // Web interface host and port
    host: "0.0.0.0",
    port: 9000,

    // Bind to specific address for IRC connections (optional)
    bind: undefined,

    // Reverse proxy configuration
    reverseProxy: true,

    // Maximum message history per channel
    maxHistory: 10000,

    // Enable HTTPS (handled by Klutch.sh, so false here)
    https: {
        enable: false
    },

    // Theme configuration
    theme: "default",

    // Prefetch URL titles and thumbnails
    prefetch: true,
    prefetchStorage: true,
    prefetchMaxImageSize: 2048,

    // File uploads
    fileUpload: {
        enable: true,
        maxFileSize: 10240, // KB
        baseUrl: null
    },

    // LDAP authentication (optional)
    ldap: {
        enable: false
    },

    // Message logging
    messageStorage: ["sqlite"],

    // Debug mode
    debug: {
        ircFramework: false,
        raw: false
    }
};

Environment Variables Reference

Variable	Required	Default	Description
THELOUNGE_HOME	No	/var/opt/thelounge	Data directory for The Lounge

Deploying on Klutch.sh

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration files to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “thelounge” or “irc-client”.

Create the Lounge App

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

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 9000.

Attach Persistent Volumes

Add persistent storage for user data and message history:

Mount Path	Size	Purpose
/var/opt/thelounge	10 GB	User data, message history, and uploads

Deploy Your Application

Click Deploy to build and launch The Lounge. Klutch.sh will provision HTTPS automatically.

Create Initial User

After deployment, access the container to create your first user account.

User Management

Creating User Accounts

In private mode, each user needs an account. Create users through the container:

The Lounge provides a command-line tool for user management. After deployment, you’ll need to create the initial admin user.

User Commands

Common user management operations:

Operation	Description
Add user	Create a new user account
Remove user	Delete a user and their data
Reset password	Generate a new password for a user
List users	Show all registered users

User Configuration

Each user can customize:

• Networks: Add and configure IRC network connections
• Themes: Choose from built-in or custom themes
• Notifications: Configure push notification settings
• Away Messages: Set automatic away messages

Connecting to IRC Networks

Adding Networks

Users add IRC networks through the web interface:

1. Log in to The Lounge
2. Click the settings icon
3. Select “Networks”
4. Click “Add network”
5. Configure the connection details

Network Configuration Options

Setting	Description
Name	Friendly name for the network
Server	IRC server hostname
Port	Server port (typically 6667 or 6697 for SSL)
TLS	Enable secure connection
Nick	Your IRC nickname
Username	IRC username (ident)
Real Name	Displayed in WHOIS queries
Password	Server password if required
Channels	Auto-join channels

Popular IRC Networks

Common networks to connect to:

• Libera.Chat: General open-source community (irc.libera.chat)
• OFTC: Open source projects (irc.oftc.net)
• Rizon: Anime and general chat (irc.rizon.net)
• Freenode: Tech communities (chat.freenode.net)

Advanced Configuration

Push Notifications

Enable push notifications for mentions:

1. Open The Lounge settings
2. Navigate to “Notifications”
3. Enable push notifications
4. Allow browser notifications when prompted

File Uploads

Configure file sharing:

• Enable in configuration: fileUpload.enable: true
• Set maximum file size: fileUpload.maxFileSize
• Files are stored in the persistent volume

Custom Themes

Install additional themes:

1. Download theme CSS files
2. Place in the themes directory
3. Select in user settings

LDAP Integration

For enterprise deployments, configure LDAP:

ldap: {
    enable: true,
    url: "ldap://ldap.example.com",
    baseDN: "ou=users,dc=example,dc=com",
    primaryKey: "uid"
}

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce strong passwords for user accounts
• HTTPS Only: Access The Lounge exclusively over HTTPS (automatic with Klutch.sh)
• Regular Updates: Keep The Lounge updated for security patches
• Network Verification: Connect only to trusted IRC networks
• NickServ Registration: Register your nickname on IRC networks

Performance Optimization

• Message Limits: Configure appropriate maxHistory for your storage capacity
• Prefetch Settings: Adjust prefetch settings based on resource availability
• File Upload Limits: Set reasonable file size limits
• User Limits: Monitor resource usage with multiple users

Backup Strategy

Protect your IRC history and configuration:

1. Back up the entire /var/opt/thelounge directory
2. Export user configurations periodically
3. Consider database backups for SQLite message storage

Troubleshooting

Cannot Connect to IRC Network

• Verify the server address and port
• Check if TLS settings match the server requirements
• Ensure the network isn’t blocked
• Try an alternative port (6667 vs 6697)

Messages Not Persisting

• Verify persistent volume is mounted correctly
• Check disk space availability
• Ensure SQLite message storage is enabled

Push Notifications Not Working

• Confirm browser supports push notifications
• Check that notifications are enabled in browser settings
• Verify HTTPS is properly configured
• Test with a different browser

Web Interface Not Loading

• Check container logs for errors
• Verify port 9000 is correctly configured
• Ensure the configuration file is valid JavaScript
• Check for syntax errors in config.js

Additional Resources

• The Lounge Documentation
• The Lounge GitHub Repository
• The Lounge Demo Instance
• The Lounge Theme Gallery
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying The Lounge on Klutch.sh provides a modern, always-connected IRC experience accessible from any device. With persistent connections, message synchronization, and a beautiful web interface, you’ll never miss important conversations again. The combination of The Lounge’s feature-rich client and Klutch.sh’s reliable infrastructure ensures your IRC presence remains constant, whether you’re at your desk or on the go.