====== IRC Setup Process ======

Initial setup and customization of the folk.zone IRC service.

===== Important Setup Notes =====

**Do NOT mount custom ircd.yaml initially**
Ergo IRCd is designed to work out of the box with a usable default config. Mounting a custom ircd.yaml file before the first run can cause segmentation faults and crashes.

**Why This Matters**
Ergo generates self-signed certificates and creates the database on first run. Custom configs must reference these correctly or the server will crash. The default config handles all of this automatically.

===== Correct Setup Process =====

**Step 1: Start with Default Config**
```bash
cd /home/brennan/folkzone-new
docker compose up -d folkzone-irc-ergo folkzone-irc-lounge
```

**Step 2: Verify Services Started**
```bash
docker compose ps folkzone-irc-ergo folkzone-irc-lounge
```

**Step 3: Check Ergo Logs for Admin Credentials**
```bash
docker logs folkzone-irc-ergo | grep "Oper username"
```
You should see something like: Oper username:password is admin:dW86Jv_Yv2ZnjwE6GnYm

**Step 4: Copy Generated Config**
```bash
docker cp folkzone-irc-ergo:/ircd/ircd.yaml /tmp/ircd.yaml
```

**Step 5: Customize Config**
Edit the config as needed. Common changes:
- Change server name from "ergo" to "irc-direct.folk.zone"
- Adjust channel settings
- Modify operator credentials

```bash
sed -i 's/name: "ergo"/name: "irc-direct.folk.zone"/' /tmp/ircd.yaml
```

**Step 6: Copy Back to Container**
```bash
docker cp /tmp/ircd.yaml folkzone-irc-ergo:/ircd/ircd.yaml
```

**Step 7: Reload Config**
```bash
docker kill -s SIGHUP folkzone-irc-ergo
```

**Step 8: Verify Reload**
```bash
docker logs folkzone-irc-ergo --tail 10
```
You should see "Rehash completed successfully"

===== First-Time Setup Checklist =====

- [ ] Start Ergo without custom config
- [ ] Verify both containers are running
- [ ] Get admin credentials from logs
- [ ] Copy generated ircd.yaml
- [ ] Customize server name
- [ ] Copy config back to container
- [ ] Reload config with SIGHUP
- [ ] Test web client at https://irc.folk.zone
- [ ] Test direct IRC connection to irc-direct.folk.zone:6697

===== See Also =====

  * [[folkzone:services:irc|IRC]] - Return to IRC overview
  * [[folkzone:services:irc:configuration|Configuration]] - Config file details
  * [[folkzone:services:irc:management|Management]] - Service management commands

Last updated: 2026-06-20
  * [[folkzone:services:start|Return to folkzone:services]]