Ergo IRC Server on AWS User Guide

Overview

This image runs Ergo, a modern IRC server (IRCd) written from scratch in Go. Unlike traditional IRC daemons that need a separate services package for accounts and channels, Ergo bundles NickServ account registration, ChanServ channel registration, native TLS, persistent message history and modern IRCv3 capabilities into a single self-contained binary, so a full featured chat network runs from one process with no external database or runtime to manage.

The server listens on the standard plaintext IRC port 6667 and the standard TLS IRC port 6697 on all interfaces. Account and channel registrations live in an embedded database on the instance. systemd starts the service on boot and restarts it on failure, and the operating system ships fully patched with unattended security updates enabled.

The image is secure by default. There is no default operator password baked into the image: a unique operator password and a unique self-signed TLS certificate for the encrypted 6697 listener are generated on the first boot of every deployed instance and never shipped inside the image, and the account and channel database is created fresh on each instance. The generated operator password is recorded in /root/ergo-credentials.txt with mode 0600, readable only by the root user.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, inbound port 6697 (TLS IRC) from the clients that will connect, and, if you want to allow unencrypted connections, inbound port 6667 (plaintext IRC)
• An IRC client (for example HexChat, irssi, WeeChat, or a mobile IRC app) to connect to the server
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Required Security Group Ports

The cloudimg image opens the following ports so the server is reachable. Configure the same rules on the security group you attach to the instance:

Plaintext IRC on port 6667 sends traffic, including passwords, in the clear. For connections that cross untrusted networks, prefer the TLS port 6697, and consider omitting port 6667 from your security group entirely so only encrypted connections are accepted.

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Ergo. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 6697 (and optionally 6667) from the clients that will connect. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation, which generates the per instance operator password and TLS certificate, takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Ergo Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 6697 and optionally 6667 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=ergo-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect Over SSH and Retrieve the Operator Password

Connect over SSH with the key pair you selected and the public IP address of the instance. The SSH login user depends on the operating system of the AMI variant you launched:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The unique operator password generated for this instance on first boot is stored in a root-only file. Print it with the following command. Keep it secret; it grants operator privileges on your IRC network:

sudo cat /root/ergo-credentials.txt

The file records the instance address, the generated server name, the plaintext and TLS endpoints, the operator name (admin) and the operator password. No default or shared operator password ships in the image.

Step 4: Verify the Server Is Running

Confirm the Ergo service is active, check its version, and confirm it is listening on the plaintext and TLS ports:

systemctl is-active ergo
/usr/local/bin/ergo --version
ss -tln | grep -E ':6667|:6697'

You should see active, the Ergo version, and listeners on *:6667 and *:6697.

The image ships a self-test that connects two real IRC clients to the running server, registers them, delivers a message from one to the other, logs in as an operator, and completes a TLS handshake on port 6697. Run it to prove the server accepts real IRC connections end to end:

sudo python3 /usr/local/lib/cloudimg/ergo-roundtrip.py

A healthy server prints a single ROUNDTRIP OK line summarising the plaintext registration, the message round-trip, the operator login (numeric 381) and the TLS handshake.

Step 5: Connect an IRC Client

Point your IRC client at the instance public IP. Use port 6697 for an encrypted (TLS) connection or port 6667 for a plaintext connection. The TLS certificate generated on first boot is self-signed, so your client will prompt you to accept it, or you can replace it with a CA-issued certificate as described in the hardening section below.

A typical client configuration is:

Server:   <public-ip>
Port:     6697 (TLS)  or  6667 (plaintext)
TLS:      on for port 6697 (accept the self-signed certificate)
Nickname: your-chosen-nick

From the irssi command-line client, for example, you would connect with:

/connect -tls -tls_verify off <public-ip> 6697

Once connected you can register your nickname and a channel using Ergo's built-in services:

/msg NickServ REGISTER your-account-password your@email.example
/join #your-channel
/msg ChanServ REGISTER #your-channel

Step 6: Become an Operator

To gain server operator privileges, log in with the operator name admin and the per instance operator password from /root/ergo-credentials.txt. Run this in your connected IRC client, replacing the password with the value you retrieved in step 3:

/oper admin your-operator-password

Ergo confirms operator status with numeric reply 381 (RPL_YOUREOPER). Operators can manage users, channels and server state; keep the operator password secret.

Step 7: Hardening for Production

The image is secure by default, but for a production network consider the following. Each of these edits Ergo's configuration at /etc/ergo/ircd.yaml and then restarts the service; make the changes with an editor and apply them with sudo systemctl restart ergo.

Replace the self-signed TLS certificate. For a public network, replace /etc/ergo/tls.crt and /etc/ergo/tls.key with a certificate issued by a trusted certificate authority (for example one obtained with Let's Encrypt for your server's domain name), so clients no longer have to accept a self-signed certificate.

Require SASL and disable public plaintext. To require authenticated connections, enable the account registration and SASL requirements in the configuration, and remove port 6667 from your security group so only the encrypted 6697 listener is reachable from untrusted networks.

Tune connection limits. Ergo's per-IP connection limits and account-registration throttling ship at safe defaults; review the limits and accounts sections of the configuration for your expected load.

After any configuration change, apply it and confirm the service is healthy:

sudo systemctl restart ergo
systemctl status ergo

Step 8: Backup and Maintenance

The account and channel database lives at /var/lib/ergo/ircd.db. To back it up, stop the service briefly, copy the database file to a safe location, and start the service again. The operating system applies security updates automatically through unattended upgrades.

To upgrade Ergo itself, replace the /usr/local/bin/ergo binary with a newer official release and restart the service; review the Ergo release notes for any configuration migration steps before upgrading.

Support

Every cloudimg image includes 24/7 technical support by email and chat. We can help with deployment, TLS certificates, SASL and account configuration, operator and privilege setup, and upgrade planning. Contact support through the channel shown on the cloudimg AWS Marketplace listing.

cloudimg is not affiliated with or endorsed by the Ergo project. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.