Deploying ngIRCd

Introduction

ngIRCd (Next Generation IRC Daemon) is a free, portable, and lightweight Internet Relay Chat server. Written from scratch in C, ngIRCd is designed to be simple to configure while supporting all the core features expected from a modern IRC server.

Unlike traditional IRC servers that evolved from complex codebases, ngIRCd was built with simplicity and portability in mind. It runs on a wide variety of platforms and is particularly well-suited for small to medium-sized IRC networks where ease of administration is a priority.

Key highlights of ngIRCd:

• Lightweight Design: Minimal resource requirements with efficient C implementation
• RFC Compliant: Follows IRC protocol standards (RFC 2810-2813, 7194)
• SSL/TLS Support: Secure connections with modern encryption
• Server Linking: Connect multiple servers for larger networks
• IPv6 Support: Full support for modern networking
• Cloaking: Host cloaking for user privacy
• Channel Modes: Standard IRC channel modes and moderation
• Ident Support: Integration with ident services
• PAM Authentication: Pluggable authentication modules
• MOTD Support: Customizable message of the day
• Simple Configuration: Single configuration file
• Cross-Platform: Runs on Linux, BSD, macOS, and more
• Open Source: Licensed under GPL

This guide walks through deploying ngIRCd on Klutch.sh using Docker, configuring your IRC server, and connecting clients.

Why Deploy ngIRCd on Klutch.sh

Deploying ngIRCd on Klutch.sh provides several advantages:

Always-On Chat Server: Your IRC server runs 24/7, providing persistent chat infrastructure.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds ngIRCd without complex configuration.

Persistent Storage: Attach persistent volumes for logs, configuration, and channel data.

TLS by Default: Klutch.sh provides automatic SSL certificates, and you can configure ngIRCd for secure IRC connections.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Low Resource Requirements: ngIRCd’s efficient design runs well with minimal resources.

Custom Domains: Assign a custom domain for a professional IRC server address.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• An IRC client for testing connections
• (Optional) A custom domain for your IRC server

Understanding ngIRCd Architecture

ngIRCd follows the standard IRC server model:

IRC Daemon: The core server process handling connections, channels, and message routing.

Configuration File: A single ngircd.conf file defining server settings, operators, and channels.

SSL/TLS Layer: Optional encryption for client and server-to-server connections.

Server Linking: Protocol for connecting multiple ngIRCd servers into a network.

Preparing Your Repository

Create a GitHub repository with your ngIRCd configuration.

Repository Structure

ngircd-deploy/
├── Dockerfile
├── ngircd.conf
├── ngircd.motd
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM alpine:latest

# Install ngIRCd
RUN apk add --no-cache ngircd openssl

# Create directories
RUN mkdir -p /etc/ngircd /var/log/ngircd /var/run/ngircd

# Copy configuration files
COPY ngircd.conf /etc/ngircd/ngircd.conf
COPY ngircd.motd /etc/ngircd/ngircd.motd

# Set permissions
RUN chown -R ngircd:ngircd /etc/ngircd /var/log/ngircd /var/run/ngircd

# Expose IRC ports
# 6667: Standard IRC
# 6697: IRC with TLS
EXPOSE 6667 6697

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

# Run ngIRCd
USER ngircd
CMD ["ngircd", "--nodaemon", "--config", "/etc/ngircd/ngircd.conf"]

Creating the Configuration File

Create ngircd.conf:

# ngIRCd Configuration

[Global]
    # Server name (should match your domain)
    Name = irc.your-domain.com

    # Administrative info
    AdminInfo1 = Your IRC Network
    AdminInfo2 = Location
    AdminEMail = admin@your-domain.com

    # Server info shown to clients
    Info = Welcome to our IRC server

    # MOTD file
    MotdFile = /etc/ngircd/ngircd.motd

    # Ports to listen on
    Ports = 6667

    # SSL/TLS ports (if configured)
    # SSLPorts = 6697

    # Maximum number of connections
    MaxConnections = 500

    # Maximum channels per user
    MaxJoins = 20

    # Maximum nickname length
    MaxNickLength = 15

    # Ping timeout (seconds)
    PingTimeout = 120

    # Pong timeout (seconds)
    PongTimeout = 20

    # Connection retry delay
    ConnectRetry = 60

[Limits]
    # Maximum connections per IP
    MaxConnectionsIP = 5

    # Maximum channels
    MaxChannels = 100

    # Maximum users in a channel
    MaxJoinsPerChannel = 1000

[Options]
    # Allow remote servers to connect
    AllowRemoteOper = no

    # Enable ident lookups
    Ident = no

    # Enable cloaking for user hostnames
    CloakHost = users.your-network.com

    # Enable IPv4
    ConnectIPv4 = yes

    # Enable IPv6
    ConnectIPv6 = no

    # PAM authentication
    PAM = no

    # Log to syslog
    SyslogFacility = local5

# IRC Operators
[Operator]
    # Operator name
    Name = admin

    # Operator password (change this!)
    Password = your_secure_password_here

    # Operator hostmask
    # Mask = *@*

# Pre-defined channels
[Channel]
    Name = #general
    Topic = General chat - Welcome!
    Modes = +nt

[Channel]
    Name = #help
    Topic = Get help here
    Modes = +nt

Creating the MOTD File

Create ngircd.motd:

 __        __   _                            _
 \ \      / /__| | ___ ___  _ __ ___   ___  | |
  \ \ /\ / / _ \ |/ __/ _ \| '_ ` _ \ / _ \ | |
   \ V  V /  __/ | (_| (_) | | | | | |  __/ |_|
    \_/\_/ \___|_|\___\___/|_| |_| |_|\___| (_)

Welcome to our IRC server!

Server Rules:
1. Be respectful to all users
2. No spam or flooding
3. Keep conversations appropriate

Available Channels:
- #general - General chat
- #help - Get assistance

Enjoy your stay!

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying ngIRCd on Klutch.sh

Customize Your Configuration

Edit ngircd.conf with your server name, admin email, and operator password.

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “ngircd” or “irc”.

Create a New App

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

Configure TCP Traffic

In the deployment settings, configure for TCP connections:

• Set the internal port to 6667 for standard IRC

Note: IRC uses TCP connections, so verify Klutch.sh TCP port configuration for your deployment.

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/log/ngircd	1 GB	Server logs

Deploy Your Application

Click Deploy to start the build process.

Configure Your Domain

If using a custom domain, configure DNS to point to your Klutch.sh app.

Connect and Test

Use an IRC client to connect to your server.

Connecting to Your IRC Server

Using Popular IRC Clients

HexChat:

1. Add a new network
2. Enter your server address and port
3. Connect and join channels

irssi:

/connect your-app-name.klutch.sh 6667
/join #general

WeeChat:

/server add myirc your-app-name.klutch.sh/6667
/connect myirc
/join #general

Web-Based Clients

For browser-based access, consider deploying a web IRC client like The Lounge or Kiwi IRC alongside ngIRCd.

Server Administration

Becoming an Operator

Use the configured operator credentials:

/oper admin your_password

Channel Management

Create and manage channels:

/join #newchannel
/mode #channel +o nickname  (give ops)
/topic #channel New topic here
/kick #channel nickname reason

Viewing Server Status

As an operator:

/stats u  (uptime)
/stats c  (connections)
/stats o  (operators)

Advanced Configuration

Enabling SSL/TLS

For encrypted connections, generate certificates and update configuration:

[SSL]
    # Certificate file
    CertFile = /etc/ngircd/server.crt

    # Key file
    KeyFile = /etc/ngircd/server.key

    # DH parameters (optional)
    DHFile = /etc/ngircd/dhparams.pem

Then enable SSL ports:

[Global]
    SSLPorts = 6697

Server Linking

Connect multiple ngIRCd servers:

[Server]
    Name = irc2.your-network.com
    Host = irc2.your-network.com
    Port = 6667
    MyPassword = outgoing_password
    PeerPassword = incoming_password

Host Cloaking

Hide user IP addresses:

[Options]
    CloakHost = users.your-network.com
    CloakHostModeX = users.your-network.com

Troubleshooting

Cannot Connect

• Verify the port is correctly configured
• Check firewall rules
• Ensure ngIRCd is running (check logs)
• Try connecting without TLS first

Authentication Failures

• Verify operator password is correct
• Check hostmask restrictions
• Review configuration syntax

Nickname/Channel Issues

• Check nickname length limits
• Verify channel mode settings
• Ensure user limits aren’t exceeded

Server Linking Problems

• Verify both servers have matching link passwords
• Check network connectivity between servers
• Ensure server names are correctly configured

Additional Resources

• ngIRCd Official Website
• ngIRCd GitHub Repository
• ngIRCd Documentation
• Modern IRC Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying ngIRCd on Klutch.sh gives you a lightweight, reliable IRC server for real-time communication. The simple configuration and low resource requirements make it easy to run your own chat infrastructure.

Whether you’re setting up a private chat server for a small team, a community chat room, or a larger IRC network, ngIRCd on Klutch.sh provides the foundation for persistent, always-available IRC communication that you control.