Skip to content
Klutch.sh Docs

Deploying Kiwi IRC

Introduction

Kiwi IRC is a modern, feature-rich web IRC client that brings IRC chat to the browser. It provides users a way to connect to IRC networks without installing desktop software, making IRC more accessible while maintaining the full functionality expected by power users.

The client connects through a WebSocket gateway (webircgateway) that bridges WebSocket connections to traditional IRC servers. This architecture allows users behind restrictive firewalls or on mobile devices to participate in IRC channels that might otherwise be inaccessible.

Key highlights of Kiwi IRC:

  • Modern Interface: Clean, responsive design that works on desktop and mobile
  • No Installation Required: Access IRC from any web browser
  • Multi-Network Support: Connect to multiple IRC networks simultaneously
  • File Sharing: Share files directly in channels (server permitting)
  • Theming: Customizable appearance with multiple themes
  • Emoji Support: Full emoji picker and Unicode support
  • URL Embedding: Automatic preview of links, images, and media
  • SSL/TLS Support: Secure connections to IRC networks
  • Notifications: Desktop notifications for mentions and messages
  • Command Aliases: Custom commands and keyboard shortcuts
  • Extensible: Plugin system for additional functionality

This guide walks through deploying Kiwi IRC on Klutch.sh using Docker, configuring the WebSocket gateway, and customizing the client for your community.

Why Deploy Kiwi IRC on Klutch.sh

Deploying Kiwi IRC on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Kiwi IRC from your Dockerfile without manual server configuration.

HTTPS by Default: Secure connections with automatic SSL certificates, required for modern browsers.

Always Available: Your IRC gateway is online 24/7 for community members.

Custom Branding: Host your own branded IRC client for your community.

No Client Install: Members can join IRC immediately from any browser.

Prerequisites

Before deploying Kiwi IRC on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and IRC concepts
  • (Optional) An IRC network you want to connect to

Understanding Kiwi IRC Architecture

Kiwi IRC consists of two components:

  1. Kiwi IRC Client: The web-based frontend users interact with
  2. webircgateway: A WebSocket to IRC bridge that handles connections

Both components need to work together for a complete deployment.

Preparing Your Repository

Repository Structure

kiwi-irc-deploy/
├── Dockerfile
├── config.json
└── .dockerignore

Creating the Dockerfile

FROM kiwiirc/kiwiirc:latest


# Copy custom configuration
COPY config.json /kiwi/static/config.json


EXPOSE 80

Creating config.json

Configure the Kiwi IRC client:

{
  "startupScreen": "welcome",
  "kiwiServer": "/webirc/kiwiirc/",
  "restricted": false,
  "theme": "default",
  "themes": [
    { "name": "Default", "url": "" }
  ],
  "startupOptions": {
    "server": "irc.libera.chat",
    "port": 6697,
    "tls": true,
    "direct": false,
    "nick": "kiwi_?"
  },
  "autoRun": "",
  "nick_blacklist": ["admin", "root", "server"],
  "showAutoComplete": true,
  "showEmojiPicker": true,
  "showColorPicker": true,
  "showSendButton": true,
  "sidebarDefault": "nicklist",
  "channelInfo": {
    "banner_file": ""
  },
  "buffers": {
    "messageLayout": "modern",
    "alert_on": "highlight",
    "timestamp_format": "%H:%M:%S",
    "show_timestamps": true,
    "scrollback_size": 250,
    "show_hostnames": false,
    "show_joinparts": true,
    "show_topics": true,
    "show_nick_changes": true,
    "show_mode_changes": true,
    "extra_formatting": true,
    "mute_sound": false,
    "show_emoticons": true,
    "show_link_previews": true,
    "inline_link_auto_previews": true
  }
}

Creating the .dockerignore File

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

Deploying Kiwi IRC on Klutch.sh

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile config.json .dockerignore
    git commit -m "Initial Kiwi IRC deployment configuration"
    git remote add origin https://github.com/yourusername/kiwi-irc-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 “kiwi-irc” or “irc-client”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your Kiwi IRC repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80

    Deploy Your Application

    Click Deploy to start the build process.

    Access Kiwi IRC

    Once deployment completes, access Kiwi IRC at https://your-app-name.klutch.sh.

Configuration Options

Startup Screen Options

Control the initial user experience:

{
  "startupScreen": "welcome",
  "startupOptions": {
    "server": "irc.libera.chat",
    "port": 6697,
    "tls": true,
    "channel": "#yourchannel",
    "nick": "guest_?"
  }
}

Startup screens:

  • welcome: Shows connection form
  • customServer: Allows custom server entry
  • hidden: Connects automatically

Pre-Configured Networks

Define networks for easy selection:

{
  "networks": [
    {
      "name": "Libera.Chat",
      "server": "irc.libera.chat",
      "port": 6697,
      "tls": true
    },
    {
      "name": "OFTC",
      "server": "irc.oftc.net",
      "port": 6697,
      "tls": true
    }
  ]
}

Restricting Access

Lock down to specific networks:

{
  "restricted": true,
  "startupOptions": {
    "server": "irc.your-network.org",
    "port": 6697,
    "tls": true
  }
}

When restricted: true, users cannot change the server.

Custom Themes

Add custom themes:

{
  "themes": [
    { "name": "Default", "url": "" },
    { "name": "Dark", "url": "static/themes/dark.css" },
    { "name": "Custom", "url": "https://example.com/theme.css" }
  ]
}

Deploying with webircgateway

For full control over the IRC gateway, deploy webircgateway alongside Kiwi IRC:

webircgateway Dockerfile

FROM kiwiirc/webircgateway:latest


COPY gateway.conf /gateway.conf


EXPOSE 8080


CMD ["/webircgateway", "--config", "/gateway.conf"]

gateway.conf

[server]
bind = "0.0.0.0"
port = 8080


[gateway]
upstream = "irc.libera.chat:6697"
upstream_tls = true


[client]
hostname_lookup = true

Production Best Practices

Security

  • Use TLS: Always connect to IRC networks over TLS
  • Restrict Networks: In public deployments, consider limiting connectable servers
  • Rate Limiting: Configure connection rate limits on the gateway

User Experience

  • Default Channel: Set a default channel for new users
  • Custom Nickname: Use pattern nick_? for random suffix
  • Helpful MOTD: Configure welcome messages

Troubleshooting Common Issues

Cannot Connect to IRC Network

Solutions:

  • Verify the IRC server address and port
  • Ensure TLS settings match the server requirements
  • Check if the IRC network blocks web clients
  • Try a different network to isolate the issue

WebSocket Errors

Solutions:

  • Ensure HTTPS is configured (required for WebSockets)
  • Check browser console for specific errors
  • Verify gateway configuration

Styling Not Applied

Solutions:

  • Verify config.json is valid JSON
  • Check browser cache (hard refresh)
  • Confirm file paths are correct

Additional Resources

Conclusion

Deploying Kiwi IRC on Klutch.sh gives you a modern, self-hosted IRC client accessible from any web browser. The combination of Kiwi IRC’s feature-rich interface and Klutch.sh’s deployment simplicity means you can provide your community with easy IRC access without managing complex server infrastructure.

Whether running a community IRC network, providing guest access to channels, or simply wanting browser-based IRC for personal use, Kiwi IRC on Klutch.sh delivers a polished, always-available solution.