Deploying InspIRCd

Introduction

InspIRCd is a modular Internet Relay Chat (IRC) daemon written in C++. Designed from the ground up to be stable, modern, and lightweight, InspIRCd powers many IRC networks around the world, from small community servers to large public networks with thousands of users.

What sets InspIRCd apart is its highly modular architecture. Nearly every feature, from SSL/TLS support to authentication methods, is implemented as a loadable module. This allows you to build exactly the IRC server you need, enabling only the features your network requires while keeping the core lean and efficient.

Key highlights of InspIRCd:

• Modular Architecture: Load only the features you need
• Modern Security: Native SSL/TLS, SASL authentication, and IRCv3 capabilities
• Scalable: Handle thousands of concurrent connections
• Linking Support: Connect multiple servers into a network
• Services Integration: Compatible with Anope, Atheme, and other services packages
• IPv6 Ready: Full IPv6 support for modern networks
• WebSocket Support: Enable web-based IRC clients
• Extensible: Write custom modules in C++
• Cross-Platform: Runs on Linux, BSD, macOS, and Windows
• Well Documented: Comprehensive configuration documentation
• Active Development: Regular updates and security patches

This guide walks through deploying InspIRCd on Klutch.sh using Docker, setting up your own IRC server.

Why Deploy InspIRCd on Klutch.sh

Deploying InspIRCd on Klutch.sh provides several advantages for hosting IRC:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds InspIRCd without manual server configuration.

Persistent Storage: Attach persistent volumes for configuration and logs. Your settings survive container restarts.

HTTPS for WebSocket: Klutch.sh provides automatic SSL certificates for WebSocket IRC access.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Reliable Uptime: Keep your IRC server online 24/7 without managing physical hardware.

Custom Domains: Assign a custom domain for your IRC network.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your InspIRCd configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of IRC concepts (channels, operators, modes)

Understanding InspIRCd Architecture

InspIRCd uses a modular design:

Core: Minimal IRC functionality handling connections and protocol basics.

Modules: Feature modules loaded at runtime:

• SSL/TLS encryption
• Authentication methods
• Channel modes
• Services linking
• WebSocket support

Configuration: XML-based configuration defining server behavior.

Linking Protocol: Spanning-tree protocol for multi-server networks.

Preparing Your Repository

To deploy InspIRCd on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

inspircd-deploy/
├── Dockerfile
├── inspircd.conf
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM inspircd/inspircd-docker:latest

# Set environment variables for configuration
ENV INSP_NET_NAME=${INSP_NET_NAME:-MyNetwork}
ENV INSP_ADMIN_NAME=${INSP_ADMIN_NAME:-Admin}
ENV INSP_ADMIN_NICK=${INSP_ADMIN_NICK:-admin}
ENV INSP_ADMIN_EMAIL=${INSP_ADMIN_EMAIL:-admin@example.com}

# Operator password (should be hashed for production)
ENV INSP_OPER_PASSWORD_HASH=${INSP_OPER_PASSWORD_HASH}

# TLS configuration
ENV INSP_TLS_CN=${INSP_TLS_CN:-irc.example.com}

# Enable/disable DNSBL
ENV INSP_ENABLE_DNSBL=${INSP_ENABLE_DNSBL:-yes}

# Create config and log directories
RUN mkdir -p /inspircd/conf /inspircd/logs /inspircd/data

# Copy configuration if provided
COPY inspircd.conf /inspircd/conf/inspircd.conf

# Expose IRC ports
EXPOSE 6667
EXPOSE 6697

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD nc -z localhost 6667 || exit 1

# Volumes for persistent data
VOLUME ["/inspircd/conf", "/inspircd/logs", "/inspircd/data"]

InspIRCd Configuration (inspircd.conf)

Create a basic inspircd.conf file:

<config format="xml">

<server
    name="irc.example.com"
    description="My IRC Server"
    network="MyNetwork"
    id="001">

<admin
    name="Admin"
    nick="admin"
    email="admin@example.com">

<bind
    address=""
    port="6667"
    type="clients">

<bind
    address=""
    port="6697"
    type="clients"
    ssl="gnutls">

<connect
    name="main"
    allow="*"
    maxchans="20"
    modes="+x"
    timeout="10"
    pingfreq="120"
    hardsendq="1048576"
    softsendq="8192"
    recvq="8192"
    threshold="10"
    commandrate="1000"
    localmax="3"
    globalmax="3">

<class
    name="ServerLinks"
    commands="*"
    privs="*"
    usermodes="*"
    chanmodes="*">

<type
    name="NetAdmin"
    classes="ServerLinks"
    host="netadmin.example.com">

<oper
    name="admin"
    hash="bcrypt"
    password="YOUR_HASHED_PASSWORD_HERE"
    host="*@*"
    type="NetAdmin">

<files motd="/inspircd/conf/motd.txt">

<channels
    users="20"
    opers="60">

<dns
    server="8.8.8.8"
    timeout="5">

<options
    prefixquit="Quit: "
    suffixquit=""
    prefixpart="&quot;"
    suffixpart="&quot;"
    fixedquit=""
    fixedpart=""
    syntaxhints="yes"
    announcets="yes"
    hostintopic="yes"
    pingwarning="15"
    serverpingfreq="60"
    defaultmodes="nt"
    moronbanner="You're banned!"
    exemptchanops=""
    invitebypassmodes="yes"
    nosnoticestack="no">

<performance
    netbuffersize="10240"
    somaxconn="128"
    limitsomaxconn="true"
    softlimit="12800"
    quietbursts="yes"
    nouserdns="no">

<security
    announceinvites="dynamic"
    hidemodes="eI"
    hideulines="no"
    flatlinks="no"
    hidewhois=""
    hidebans="no"
    hidekills=""
    hidesplits="no"
    maxtargets="20"
    customversion=""
    operspywhois="no"
    runasuser=""
    runasgroup=""
    restrictbannedusers="yes"
    genericoper="no"
    userstats="Pu">

<limits
    maxnick="32"
    maxchan="64"
    maxmodes="20"
    maxident="11"
    maxquit="255"
    maxtopic="307"
    maxkick="255"
    maxgecos="128"
    maxaway="200">

<log method="file" type="* -USERINPUT -USEROUTPUT" level="default" target="/inspircd/logs/ircd.log">

<whowas
    groupsize="10"
    maxgroups="100000"
    maxkeep="3d">

<!-- Modules -->
<module name="cap">
<module name="ssl_gnutls">
<module name="sasl">

<gnutls
    certfile="/inspircd/conf/cert.pem"
    keyfile="/inspircd/conf/key.pem"
    dhbits="2048"
    priority="NORMAL">

</config>

Environment Variables Reference

Variable	Required	Default	Description
INSP_NET_NAME	No	MyNetwork	IRC network name
INSP_ADMIN_NAME	No	Admin	Admin display name
INSP_ADMIN_NICK	No	admin	Admin nickname
INSP_ADMIN_EMAIL	No	-	Admin email address
INSP_OPER_PASSWORD_HASH	Yes	-	Hashed operator password
INSP_TLS_CN	No	-	TLS certificate common name
INSP_ENABLE_DNSBL	No	yes	Enable DNS blocklist checking

Deploying InspIRCd on Klutch.sh

Once your repository is prepared, follow these steps to deploy InspIRCd:

Generate Operator Password Hash

Create a secure password hash for oper access:

# Using bcrypt (recommended)
htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'

Or use InspIRCd’s built-in tool if available.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile inspircd.conf .dockerignore
git commit -m "Initial InspIRCd deployment configuration"
git remote add origin https://github.com/yourusername/inspircd-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “irc” or “inspircd”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your InspIRCd Dockerfile.

Configure TCP Traffic

IRC uses TCP connections. In the deployment settings:

• Select TCP as the traffic type
• Set the external port to 8000
• The internal port maps to 6667 (standard IRC) or 6697 (SSL)

Set Environment Variables

In the environment variables section, add:

Variable	Value
INSP_NET_NAME	Your network name
INSP_ADMIN_EMAIL	Your admin email
INSP_OPER_PASSWORD_HASH	Your hashed operator password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/inspircd/conf	1 GB	Configuration files
/inspircd/logs	5 GB	Server logs
/inspircd/data	1 GB	Persistent data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the InspIRCd server

Connect to Your Server

Once deployment completes, connect using an IRC client:

• Server: your-app-name.klutch.sh
• Port: 8000 (the external TCP port)

IRC Server Administration

Becoming an Operator

Once connected, authenticate as an operator:

/OPER admin yourpassword

Managing Channels

As an operator, you can:

/JOIN #channel
/MODE #channel +o nickname
/KICK #channel nickname reason
/TOPIC #channel New topic here

Server Commands

Useful oper commands:

/REHASH          # Reload configuration
/STATS u         # Server uptime
/STATS c         # Connection classes
/LUSERS          # User statistics
/MAP             # Network map

Essential Modules

Load useful modules for a feature-rich server:

Module	Purpose
ssl_gnutls	TLS encryption
sasl	SASL authentication
cap	IRCv3 capabilities
cloaking	Hostname masking
services_account	Services integration
chanprotect	Channel founder protection
websocket	WebSocket connections
password_hash	Password hashing

Troubleshooting Common Issues

Cannot Connect

Symptoms: IRC client fails to connect.

Solutions:

• Verify port configuration matches your client
• Check firewall allows TCP connections
• Review InspIRCd logs for connection errors

Oper Authentication Fails

Symptoms: /OPER command rejected.

Solutions:

• Verify password hash is correct
• Check oper block host mask matches your connection
• Ensure you’re using the correct username

TLS Not Working

Symptoms: SSL connections fail.

Solutions:

• Verify certificate and key files exist
• Check certificate file permissions
• Review GnuTLS module configuration

Additional Resources

• Official InspIRCd Website
• InspIRCd Documentation
• InspIRCd GitHub Repository
• InspIRCd Docker Image
• Klutch.sh Deployments

Conclusion

Deploying InspIRCd on Klutch.sh gives you a powerful, modern IRC server with automatic builds and persistent configuration. The modular architecture allows you to customize your server exactly to your needs, whether you’re running a small community chat or building a larger IRC network.

Whether you’re creating a private team chat, building a gaming community, or hosting a public IRC network, InspIRCd on Klutch.sh provides the foundation for reliable, feature-rich real-time communication.