Ergo IRC Server Documentation

Ergo uses user accounts to enable features like multiple clients per nickname.

Register a Nickname

Use the NickServ service to register your current nickname as an account: /msg NickServ register <password>

Note: It is highly recommended to enable SASL in your IRC client to ensure automatic login and prevent nickname claiming issues.

Register a Channel

Once you have a registered account, you can claim ownership of a channel:

1. Join the channel: /join #channel
2. Register the channel: /CS REGISTER #channel

Registered channels will persist ownership, topics, and modes.

By default, Ergo channels are ephemeral and disappear when empty or upon server restart. To make a channel permanent and maintain control over its settings, register it via ChanServ.

Requirements:

1. You must be an operator (+o mode, often displayed as @) in the channel.
2. The channel must already exist (use /join #channel if it does not).

/msg ChanServ register #myChannel

To run Ergo in a Docker container:

1. Pull the stable image: docker pull ghcr.io/ergochat/ergo:stable.
2. Create a volume for persistent data: docker volume create ergo-data.
3. Run the container, mapping the default ports (6667 for plaintext, 6697 for TLS) and mounting the volume to /ircd.

docker pull ghcr.io/ergochat/ergo:stable
docker volume create ergo-data
docker run -d --name ergo -v ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable

On the first run, Ergo generates a default configuration and a randomized oper password. This information is output to stdout. You can retrieve it using docker logs.

docker logs ergo

To send updated source strings to CrowdIn for translation, follow these steps:

1. Navigate to the project base directory.
2. Install the required Python dependencies: pyyaml and docopt.
3. Execute the translation update script.
4. Commit the resulting changes.

CrowdIn will automatically pick up the new translation files. Use the INFO command to verify if credits strings have been updated or translated correctly.

To restrict access to a registered channel, use the +i (invite-only) mode and manage access via exceptions or persistent privileges:

1. Set the channel to invite-only: /mode #example +i
2. Add users to the invite exception list: /mode #example +I alice
3. Grant persistent voice: /msg ChanServ AMODE #example +v alice
4. Grant persistent operator privileges: /msg ChanServ AMODE #example +o bob

By default, disconnecting from the server makes you appear as 'quit' to others. To remain 'present' on the server (joined to channels and able to receive DMs) even when your client is disconnected, enable always-on mode via NickServ.

/msg NickServ set always-on true

Ergo includes built-in account registration via NickServ.

Password-based registration

To register an account using a standard password (where your current nickname becomes your username): /NS REGISTER <password> or /msg nickserv register <password>

TLS Certificate-based registration (SASL EXTERNAL)

To register an account using a TLS client certificate instead of a password: /NS REGISTER *

Logging in

• SASL: Configure your IRC client to use SASL with your username and password.
• Non-SASL clients: Use the server password (PASS) field in your client with the format accountname:accountpassword.

You can import user and channel registrations from Anope or Atheme databases into Ergo using the provided migration tools.

1. Download anope2json.py or atheme2json.py from the Ergo stable release.
2. Copy your existing database file.
3. Convert the database to JSON using Python: python3 <tool> <input_db> <output.json>.
4. Prepare your ircd.yaml.
5. Import the data using ergo importdb ./output.json.
6. Run ergo mkcerts if TLS is required.
7. Start Ergo with ergo run.

python3 ./anope2json.py anope.db output.json
ergo importdb ./output.json
ergo mkcerts
ergo run

To become an operator on your Ergo instance:

1. Pick a strong password.
2. Generate a hash of the password using the command line: ergo genpasswd.
3. Copy the resulting hash into the opers section of your ircd.yaml file.
4. Connect to the server and issue the IRC command: /oper admin <your_password> (where admin is the operator name defined in your config).

The default configuration provides an admin operator with full privileges.

ergo genpasswd
# Then in IRC client:
/oper admin mysecretpassword

If you need to manually upload source strings to CrowdIn:

1. Navigate to the project base directory.
2. Install pyyaml and docopt via pip.
3. Run the ./updatetranslations.py script.
4. Install the CrowdIn CLI tool.
5. Ensure your CrowdIn API key is configured in ~/.crowdin.yaml.
6. Run the upload command.

pip3 install pyyaml docopt
./updatetranslations.py run irc languages
crowdin upload sources