SELF-HOSTING GUIDE

Install LXBG on your own server

The core architecture consists of the web app and database, LXBGIRCd, the authentication bridge, the WebSocket bridge and, depending on the package, LXBG Services. This guide describes the documented Community Edition installation workflow.

Recommended: Debian 12, öffentliche IPv4, Domain mit TLS, PHP 8.2+, MariaDB/MySQL, Python 3 und systemd. Always create a backup before making server changes.

1 · Download and extract the package

Download the Community Edition or individual components from the downloads page and extract them into a working directory. Only run installation scripts from packages obtained directly from LXBG.

unzip LXBG-Community-Edition-1.1.zip
cd LXBG-Community-Edition-1.1
sudo ./install.sh

By default, the installer copies Community Edition to /opt/lxbg-ce, creates the system user lxbg and prepares runtime directories. Public services are deliberately not started automatically without review.

2 · Configure the database

Create a dedicated UTF-8 MariaDB/MySQL database and user. Then import the included schema.sql. Kopiere config.example.json nach config.json, enter database credentials and the IRC hostname, and protect the file with permissions 600. Never store credentials in the public web root.

3 · Deploy the web app

Serve the included web directory using PHP 8.2+ with nginx or Apache and HTTPS. Adapt the private database/bootstrap path to your server layout. Domain, TLS certificate and web root vary by hosting provider and must be configured explicitly.

4 · Enable the authentication bridge

The authentication bridge connects the IRC daemon to LXBG accounts. Use the included lxbg-auth.service.example as a systemd template. By default, it uses /run/lxbg-ce/auth.sock und /opt/lxbg-ce/config.json.

5 · Start LXBGIRCd

In the included lxbg-ircd.service.example check the server name, ports and paths to the TLS certificate and private key. Only then copy the unit to /etc/systemd/system/lxbg-ircd.service and enable it.

sudo systemctl daemon-reload
sudo systemctl enable --now lxbg-auth
sudo systemctl enable --now lxbg-ircd
sudo systemctl status lxbg-auth lxbg-ircd

The example uses IRC on port 6667 and IRC/TLS on 6697 by default. You can then test /VERSION with an IRC client; LXBGIRCd 1.0 should respond.

6 · Browser/WebSocket bridge

The included WebSocket bridge runs locally for browser chat (example: 127.0.0.1:8000). Enable the lxbg-ws.servicetemplate and reverse-proxy the public path /irc-ws/ through nginx/Apache with WebSocket upgrade headers. Do not expose the local bridge directly to the internet unless necessary.

sudo systemctl enable --now lxbg-ws
sudo systemctl status lxbg-ws

7 · Install LXBG Services 1.1

Entpacke LXBG-Services-1.1.zip, importiere schema.sql and install pymysql sowie argon2-cffi. Then copy config.example.json nach /etc/lxbg-services/config.json and enter the database, server ID, IRC uplink and link password. Then start services/daemon.py; and, if using the LXBG website, also start services/auth_bridge.py.

python3 services/daemon.py --config /etc/lxbg-services/config.json --db-test
python3 services/daemon.py --config /etc/lxbg-services/config.json

Important since 1.1: LXBG Services are our own services layer. LXBG Account Services, LXBG Channel Services and SASL are included in the base package. LXBG Services 1.1 manages accounts, channel permissions and SASL independently. The server ID, link password and IRCd link configuration must match for the uplink.

8 · Restart and functional testing

sudo systemctl status lxbg-auth lxbg-ircd lxbg-ws
sudo journalctl -u lxbg-ircd -n 50 --no-pager

Then test HTTPS, registration/login, IRC over TLS, browser chat and, if installed, LXBG Account Services/LXBG Channel Services. Premium modules also include their own README/installation guides.

Prefer a managed installation?

JKWEB can install LXBG on a compatible Linux server for 149,00 € einmalig. Server, domain and custom development are not included.

Request installation → Back to downloads