Skip to content

01. Getting Started

Jump to bottom Edit New page
github-actions[bot] edited this page Feb 26, 2025 · 1 revision

Installing

A complete Kiwi IRC installation consists of two components: a server-side webircgateway instance and the kiwiirc client files.

The webircgateway facilitates websocket access to IRCd's that do not support websockets. Additionally, it offers a polling-based fallback for networks that restrict websocket connections.

If your IRCd supports websockets and you prefer a direct connection, you only need the kiwiirc client files. Once built, these files are static HTML/JS/CSS and can be served using any HTTP server like Apache or Nginx. For detailed information on configuring static/config.json to establish a direct connection, kindly refer to the Configuration - Startup Options section.


Packages

Kiwi IRC provides prebuilt release packages for various operating systems and architectures. You can obtain them from GitHub Releases

The installation method may vary depending on the distribution you are using. We recommend searching for instructions specific to your distribution.

Note: The packages include the webircgateway binary and service, both named "kiwiirc" for your convenience.


Here are some example commands for common distributions:

Debian / Ubuntu

sudo dpkg -i kiwiirc-server_v1.7.0-2_linux_amd64.deb

Fedora / CentOS

sudo rpm -i kiwiirc-server_v1.7.0-2_linux_amd64.rpm

Once you have successfully installed the appropriate package, refer to Configuration for further guidance.


Manual

A manual installation of Kiwi IRC is possible using the .zip files from GitHub Releases, Builds Server, or by building from the source code.

For a full Kiwi IRC installation, when using the Builds Server or sources, you will need both webircgateway and kiwiirc.

Manual installation is an advanced method and offers flexibility based on personal preferences. As such, we do not provide detailed instructions. However, you can find an example systemd service file here.


Configuration

Following the successful installation of the packages, the configuration files can be located in the directory /etc/kiwiirc/.

There are separate files for the server and the client. The server is purposely kept as simple as possible to keep it light and secure. This is where you will be limiting the IRC networks users can connect to and adding webirc/cgi:irc passwords. This is where all the IRC connections are made on behalf of the client sat in the users browser.

The client config file handles how the webpage looks, how it loads, and the default client settings that your users see.


config.conf

The config.conf file is used to configure the webircgateway service, and any changes made to it will necessitate a service restart. The common method for restarting the service is systemctl restart kiwiirc, although this may vary depending on your distribution.

By default, webircgateway attempts to utilize port 80. However, if you have an HTTP server already installed, that port might be in use. In such cases, it is advisable to modify the port and then implement a reverse proxy for webircgateway using your HTTP server. Below are example reverse proxy configurations for Apache and Nginx. Both configurations assume the following webircgateway settings:

# The websocket / http server
[server.1]
bind = "127.0.0.1"  # localhost
port = 7778

If you are using Kiwi IRC for a single network then you can edit the example upstream called [upstream.1]. By default, users using this server will only be able to connect to this upstream and no others.


Security Considerations

By default, anyone can connect to your server from any website. In most cases this will be undesirable as it opens your server up for abuse. E.g. Someone may put their own version of Kiwi IRC on a popular website that auto connects to your server causing a flood of spam.

To work around this, the sever allows you to list specific websites that may connect to your server. This makes use of the browser "Origin" headers that all browsers use today.

In the config file is a section [allowed_origins] whereby you can list the website domain names that you want to allow to connect.

You may use wild cards here. E.g. If you have a website example.com, you may want to allow *.example.com to allow all sub domains (and HTTP/HTTPS) on your website.


client.json

The client.json file is responsible for configuring the kiwiirc client. Changes to this file only require a browser refresh to apply the new configuration. However, please note that the browser may cache the configuration in certain situations.

For a comprehensive list of possible configuration options, please refer to Configuration Options and/or configTemplates.js.


plugins

Compiled plugins should be copied to /usr/share/kiwiirc/static/plugins/ once this is completed you will need to add the details of the plugin to client.json. Most plugins Github pages should contain details on how to load and configure the plugin but for those that do not here is an example:

"plugins": [
    { "name": "customise", "url": "static/plugins/customise.html" },
    { "name": "conference", "url": "static/plugins/plugin-conference.js" }
]

Switching the packaged client to github master

Installing from the pre-built packages provide a stable and known version of the web client. Using the master branch will include the latest features but may not be as stable - use at your own risk.

This guide will explain updating the Kiwi IRC frontend client only.

note: Choose a location for your new Kiwi IRC client. This guide will use /usr/share/kiwiirc_master/.

note: If updating a previous build it is recommended to remove static/config.json from the downloaded files before copying. To prevent your existing configuration from being overwritten.


  1. Downloading the latest Kiwi IRC client.

    Either download and build from github, or download a pre-built version from our builds server. Copy the compiled files [/dist/ from source, /kiwiirc/ from builds server] to /usr/share/kiwiirc_master/. There should be an index.html and static directory.

  2. Transfer configuration and plugins.

    The new files will have a clean config and not be linked to the one in /etc/kiwiirc/. You can either copy over your old configuration or relink it to the one in /etc/kiwiirc/.

    Relinking Command:

    rm /usr/share/kiwiirc_master/static/config.json
ln -s /etc/kiwiirc/config.json /usr/share/kiwiirc_master/static/config.json

    At this stage you will also want to copy over any plugins or themes that you added to the previous version.

  3. Reconfigure the server's webroot

    Edit /etc/kiwiirc/config.conf and change the webroot option to /usr/share/kiwiirc_master/.

    [fileserving]
enabled = false
webroot = /usr/share/kiwiirc_master/

    Don't forget after editing config.conf it will necessitate a service restart. The common method for restarting the service is systemctl restart kiwiirc, although this may vary depending on your distribution.

    If you are using reverse proxy you may also need to update the DocumentRoot / root within its configuration file.


Checking the client version

It is possible to get information of the current build of the client by opening the browser's dev tools (often via F12) while on the kiwiirc page.

From inside the console tab input the following and press enter:

kiwi.commithash

which will give you the short kiwiirc commit hash for the build.

Add a custom footer
Add a custom sidebar
Clone this wiki locally