evrd

Features

• Always connected. evrd keeps each of your networks connected, reconnects with backoff, fails over across several servers, and keeps the history.
• Bring any client. Attach irssi, WeeChat, HexChat, … with a server password and get what you missed, then the live feed. Several clients and the web app share one connection and stay in sync.
• A web app too. Chat in the browser, with unread counts, mentions, a "missed while away" marker, members and topics. Manage networks, client passwords and your account; admins manage users and server settings.
• ZNC-style settings, without the config file. Per network: servers, nick and alternate nick, ident, SASL, certificate trust (fingerprints, self-signed servers), channel keys and detached channels, encodings, flood protection. Per user: playback, timestamps, CTCP replies, allowed addresses. *status works from any client.
• Accounts. Password or single sign-on (OpenID Connect: Logto, Authentik, Keycloak, …), per-device IRC client passwords, roles and per-user limits. Saved network passwords are encrypted at rest.
• Grows with you. One container on a small VPS, or several nodes behind a load balancer sharing Postgres and ScyllaDB.
• Dashboards. Optional metrics (OpenTelemetry → VictoriaMetrics) for traffic charts, lag and link health.

Quick start

You need a Linux host with Docker (Compose v2) — or, on OpenBSD, see Installing on OpenBSD: one script, no Docker.

evrd runs as three containers: the bouncer, its web app, and Postgres. Chat history is kept on a volume.

1. Get the deployment files

git clone https://github.com/4evrd/evrd.git
cd evrd/deploy/docker

(You only need the three files in deploy/docker/: docker-compose.yml, evrd.conf and .env.example.)

The images are published to GitHub's registry as ghcr.io/4evrd/evrd and ghcr.io/4evrd/evrd-web (amd64 and arm64), no login needed.

2. Set the secrets

cp .env.example .env
docker run --rm --entrypoint evrctl ghcr.io/4evrd/evrd genkey   # → EVRD_SECRET_KEY

Put that key and a long random POSTGRES_PASSWORD in .env. The key encrypts saved network passwords — keep a copy somewhere safe; without it they can't be read back.

3. Say where it lives

In evrd.conf, set public_url (the web app's address) and irc_host (what users type into their IRC client):

public_url https://bnc.example.org
irc_host   bnc.example.org

4. Start it and make the first admin

docker compose up -d
docker compose exec evrd evrctl user add -admin yourname 'a-long-password'

5. Sign in

Open the web app — http://<host>:8080, or your public_url once HTTPS is set up (below) — sign in, and Add network (e.g. irc.libera.chat, port 6697, TLS on). evrd connects straight away. To use a desktop client, see Connecting an IRC client.

Testing without HTTPS? Set cookie_secure no in evrd.conf (and back to yes for real use), or the browser won't keep you signed in over plain http.

HTTPS

Put any reverse proxy with TLS in front of the web app on port 8080; it serves the app and proxies the API (including the WebSocket) to evrd. With Caddy, the whole config is:

bnc.example.org {
    reverse_proxy localhost:8080
}

IRC clients connect to evrd directly on 6697 (TLS). evrd makes a self-signed certificate for it unless you pick another source, in the web app under Admin → Settings → HTTPS & TLS (or tls in evrd.conf): Let's Encrypt, got and renewed by evrd itself (tls acme), or your own files (tls_cert, tls_key, re-read when they change; in Docker, mount them through the ./certs volume in docker-compose.yml).

evrd can also serve the web app over HTTPS itself, with no proxy at all — see HTTPS and certificates.

Connecting an IRC client

Each user connects to irc_host, port 6697 with TLS, and a server password of username/network:password:

server:   bnc.example.org/6697   (TLS on)
password: yourname/libera:a-long-password

The password is your account password, or — better — an IRC client password made for that device on the web app's IRC clients page (accounts that use single sign-on need one). The page has copy-paste setup for HexChat, irssi and WeeChat. More, including the *status commands: docs/irc-clients.md.

Configuration

Settings come from evrd.conf, and most of them can be changed later in the web app under Admin → Settings (those are stored in the database and win over the file; environment variables win over both). Things you might set:

public_url, irc_host	where users reach the web app and point IRC clients
max_networks, max_clients, backlog_lines	per-user limits (0 = unlimited)
oidc_issuer, oidc_client_id, oidc_client_secret	single sign-on with any OpenID Connect provider
password_login	turn password sign-in off when everyone uses SSO
tls_cert, tls_key	a real certificate for IRC clients
bindhost	local addresses users may connect from (vhosts)
listen	extra listeners, e.g. plain IRC on 6667
network_directory	the list of public networks offered on Add network (evrd.sh's, a file of your own, or off)

Every directive, network and account settings, and how the web app's settings layer over the file: docs/configuration.md.

Single sign-on

Create an OpenID Connect app in your provider with the redirect URI <public_url>/auth/callback, then:

This is the beginning of the README. Read the rest at the original. Read the full README ↗