ircbits.com

Docs / Ergo setup guide: a modern IRC server in one evening

Ergo setup guide: a modern IRC server in one evening

Updated June 4, 2026

Ergo (formerly Oragono) is the reason running your own IRC server stopped being a sysadmin hobby and became an evening task: one binary, one YAML file, with services and message history built in. This walkthrough takes you from zero to a TLS-enabled server with registered accounts.

1. Install

Download the release tarball for your platform from the Ergo project (or go install); inside you get the ergo binary, a default ircd.yaml, and language files. Create a user and directory for it:

sudo useradd -r -d /opt/ergo ergo
sudo mkdir -p /opt/ergo && sudo chown ergo /opt/ergo
# unpack the tarball into /opt/ergo

2. TLS first

Get a certificate for your hostname (certbot/Let's Encrypt), then point the config's listener at it. In ircd.yaml:

server:
  name: irc.example.com
  listeners:
    ":6697":
      tls:
        cert: /opt/ergo/fullchain.pem
        key: /opt/ergo/privkey.pem

Skip the plaintext :6667 listener entirely unless you have a reason; it is 2026.

3. The settings that matter

Work through ircd.yaml — it is long but readable — and decide:

  • network: name: — what your network calls itself.
  • accounts: registration: — enable it; optionally require email verification (configure the outbound mail settings) so registration means something.
  • accounts: nick-reservation: — set method strict so registered nicks are actually protected, Ergo's built-in NickServ enforcing it.
  • history: — Ergo's killer feature. Enable it and set a retention window; clients supporting IRCv3 chathistory (goguma, gamja, Halloy…) then get scrollback with no bouncer anywhere.
  • limits: and the default modes — sane out of the box, worth a read.

4. Run it

A minimal systemd unit:

[Service]
User=ergo
WorkingDirectory=/opt/ergo
ExecStart=/opt/ergo/ergo run --conf /opt/ergo/ircd.yaml
Restart=always

systemctl enable --now ergo, connect your client to irc.example.com:6697 with TLS, and register: /msg NickServ REGISTER password you@example.com.

5. Make yourself an operator

Generate a password hash with ergo genpasswd, add yourself under opers: in the config, reload, and /oper yourname yourpassword. Now register your main channel with the built-in ChanServ and set its modes.

Maintenance notes

Ergo rehashes config on SIGHUP (/rehash as oper) — no restart for most changes. Certificate renewal plus rehash is the only recurring chore. Back up the datastore file; it holds your accounts, channels, and history. From here, invite your community — client recommendations make a good welcome message.