An extended fork of Soju, the IRC bouncer by Simon Ser (emersion), adding upstream WEBIRC forwarding and other features useful for BNCs serving a specific IRC network.
This is an unofficial fork based on Soju commit
07baba07f11c5e19aeaa5cbe21d39fff0b9df44e (2024-03-04).
The upstream project lives at git.sr.ht/~emersion/soju (canonical) with a mirror at github.com/emersion/soju.
This fork was originally developed for an internal IRC network. It is published here so others can benefit from the added features. All added features are opt-in via configuration: with no fork-specific configuration, the binary behaves like a stock Soju.
By default Soju connects to the upstream IRC server presenting the BNC's own IP address,
so every bounced user appears to originate from the BNC host. This fork adds support for
forwarding the real client IP to the upstream server via the WEBIRC command, so the
upstream server sees each user individually.
Useful for:
- Per-user moderation (K-lines / G-lines by real IP)
- Mobile / desktop apps that want per-user identification through the BNC
- Anti-abuse / anti-flood by real IP
- Analytics / geolocation
Configuration: see config.example.ini (WEBIRC password directive).
Skip storing messages in the message store for channels matching configured glob patterns. Useful for high-volume bot / automation channels where message history is not desired or would bloat the database.
Configuration: see config.example.ini (no-log-channels directive).
For BNCs dedicated to a single IRC network, auto-create a network with the configured URL for every new user. This removes the need for each user to manually configure their network after registration.
Configuration: see config.example.ini (default network URL directive).
Optional bot that connects to the upstream IRC server and joins a services channel, providing an interface for admin commands. Disabled by default; enable only if you control the upstream server and want in-IRC administration.
Configuration: see config.example.ini (control-bot section).
A standalone HTTP server (main.go) that exposes sojuctl commands via
POST /execute with bearer-token authentication. Useful for integrating Soju
administration with external tools (admin panels, workflow automation like n8n, etc.).
Environment variables:
SOJU_GATEWAY_TOKEN— bearer token for authentication (required)SOJU_GATEWAY_PORT— listen port (default:10001)
Example:
curl -X POST http://localhost:10001/execute \
-H "Authorization: <token>" \
-d "user list"- Copy
config.example.initoconfig/config.iniand adjust - Copy
.env.exampleto.envand setSOJU_GATEWAY_TOKEN docker-compose up -d
Requires Go 1.19+ (the vendored soju/ is built with 1.19+; the Dockerfile uses 1.21).
cd soju && make soju
cd .. && go build -o soju_gateway main.goSee config.example.ini for all configuration directives, including those added by this
fork. The format is a superset of Soju's — a stock Soju config file works unchanged; all
fork-specific directives are optional.
- Config format: superset of upstream Soju — stock Soju configs work as-is
- Database schema: unchanged from upstream Soju
- Wire protocol: unchanged; standard IRC clients work without modification
This fork is based on a specific Soju commit and is not actively synchronized with upstream. Given the AGPL-3.0 license and Soju's active development, users are encouraged to check upstream Soju for the latest features and security fixes, and to port this fork's changes forward if needed.
AGPL-3.0-only, inherited from Soju upstream. See LICENSE.
- Simon Ser (emersion) and Soju contributors — the original Soju bouncer this fork is built on
- This fork's added features were developed independently for an internal IRC network
This is an archive-style fork. Issues and PRs are accepted but response may be slow. For general Soju features and improvements, please contribute directly to upstream Soju.