# IRC Server Setup & Connection Guide

## Server Setup

### 1. Configure Your Server

Edit `irc-public.nix` and update these important fields:

```nix
Name = irc.yourdomain.com          # Your actual domain
AdminInfo1 = Your Name             # Your name
AdminInfo2 = Your Community Server # Server description
AdminEMail = admin@yourdomain.com  # Your email
CloakHostSalt = your-random-salt-here  # Generate random string
```

Generate a random salt for host cloaking:
```bash
openssl rand -hex 32
```

### 2. Set Up Operator Password

Generate a secure password hash:
```bash
# Generate password hash
htpasswd -nBC 10 "" | cut -d: -f2
```

Update the `[Operator]` section with the hash:
```nix
[Operator]
Name = admin
Password = $2y$10$your-generated-hash-here
Mask = *!*@yourdomain.com  # Restrict to your domain
```

### 3. Enable in Your NixOS Configuration

Add to your `flake.nix` modules:
```nix
modules = [
  ./configuration.nix
  ./irc-public.nix  # Add this line
  # ... other modules
];
```

### 4. Set Up DNS

Point your domain to your server's IP:
```
A     irc.yourdomain.com    -> YOUR_SERVER_IP
AAAA  irc.yourdomain.com    -> YOUR_SERVER_IPv6 (optional)
```

### 5. (Optional) Enable SSL/TLS

For encrypted connections, uncomment the SSL section in `irc-public.nix` and generate certificates:

**Option A: Let's Encrypt (Recommended)**
```nix
# Uncomment in irc-public.nix:
security.acme = {
  acceptTerms = true;
  defaults.email = "admin@yourdomain.com";
  certs."irc.yourdomain.com" = {
    group = "ngircd";
    postRun = "systemctl reload ngircd.service";
  };
};
```

**Option B: Self-Signed Certificates**
```bash
sudo mkdir -p /etc/ngircd/ssl
cd /etc/ngircd/ssl

# Generate DH parameters
openssl dhparam -out dhparams.pem 2048

# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout server-key.pem \
  -out server-cert.pem -days 365 -nodes \
  -subj "/CN=irc.yourdomain.com"

sudo chown ngircd:ngircd /etc/ngircd/ssl/*
sudo chmod 600 /etc/ngircd/ssl/server-key.pem
```

### 6. Deploy

```bash
sudo nixos-rebuild switch --flake /home/tony/nixos-dotfiles#nixos-btw
```

### 7. Verify Server is Running

```bash
systemctl status ngircd.service
ss -tlnp | grep 6667
```

---

## How to Connect to the Server

### For Users

#### Desktop IRC Clients

**HexChat (Linux/Windows/Mac)**
1. Install HexChat from your package manager or [hexchat.github.io](https://hexchat.github.io/)
2. Open HexChat and go to Network List
3. Click "Add" and name it "Community Server"
4. Click "Edit" and add:
   - Server: `irc.yourdomain.com/6667` (or `/6697` for SSL)
   - Check "Use SSL" if using port 6697
5. Set your nickname
6. Click "Connect"
7. Join channels: `/join #general`

**WeeChat (Linux/Mac Terminal)**
```bash
# Install
sudo apt install weechat  # Debian/Ubuntu
# or: brew install weechat  # macOS

# Run and configure
weechat
/server add community irc.yourdomain.com/6667
/set irc.server.community.nicks "yournick"
/connect community
/join #general
```

**Irssi (Linux/Mac Terminal)**
```bash
# Install
sudo apt install irssi  # Debian/Ubuntu

# Run and connect
irssi
/network add -nick yournick Community
/server add -auto -network Community irc.yourdomain.com 6667
/connect Community
/join #general
```

**mIRC (Windows)**
1. Download from [mirc.com](https://www.mirc.com/)
2. Tools → Options → Connect
3. Add server:
   - Description: Community Server
   - IRC Server: irc.yourdomain.com
   - Ports: 6667 (or 6697 for SSL)
4. Connect and join #general

**Textual (macOS)**
1. Download from Mac App Store
2. Server → New Server
3. Enter server details:
   - Address: irc.yourdomain.com
   - Port: 6667 (or 6697 for SSL)
4. Connect

#### Mobile IRC Clients

**Android - Revolution IRC**
1. Install from Google Play Store
2. Add Server:
   - Name: Community Server
   - Address: irc.yourdomain.com
   - Port: 6667 (or 6697 for SSL)
3. Set nickname and connect
4. Join #general

**iOS - Palaver**
1. Install from App Store
2. Add Network:
   - Server: irc.yourdomain.com
   - Port: 6667
3. Set nickname and connect

#### Web Browser (if TheLounge enabled)

Visit: `http://your-server-ip:9000`
- Register an account
- Auto-connects to the server
- Join channels from the interface

---

## Basic IRC Commands

### Essential Commands
```
/nick NewNickname          - Change your nickname
/join #channel             - Join a channel
/part #channel             - Leave a channel
/msg nickname message      - Send private message
/query nickname            - Open private chat window
/quit                      - Disconnect from server
```

### Channel Commands
```
/topic New topic text      - Set channel topic (if op)
/me does something         - Send action message
/names                     - List users in channel
/whois nickname           - Get info about user
```

### Channel Operator Commands
```
/mode #channel +o nick     - Give operator status
/mode #channel +v nick     - Give voice (can talk in moderated)
/mode #channel +m          - Moderated channel
/mode #channel +t          - Only ops can set topic
/kick #channel nick        - Kick user from channel
/mode #channel +b nick!*@* - Ban user
```

---

## Default Channels

- **#general** - Main discussion channel
- **#announcements** - Server announcements (moderated, read-only for regular users)
- **#support** - Help and support
- **#offtopic** - Off-topic discussions

---

## Server Administration

### Becoming an Operator
```
/oper admin your-password
```

### Managing Users
```
/kill nickname reason       - Disconnect user
/gline *!*@hostname 3600 reason  - Global ban for 1 hour
```

### Server Commands
```
/rehash                    - Reload configuration
/restart                   - Restart server
```

---

## Troubleshooting

### Can't Connect
1. Check firewall: `sudo ufw status` or `sudo firewall-cmd --list-ports`
2. Verify service: `systemctl status ngircd.service`
3. Check logs: `journalctl -u ngircd.service -f`
4. Test locally: `telnet localhost 6667`

### SSL Connection Issues
1. Verify certificates exist in `/etc/ngircd/ssl/`
2. Check certificate permissions: `ls -la /etc/ngircd/ssl/`
3. Test SSL: `openssl s_client -connect irc.yourdomain.com:6697`

### Port Already in Use
```bash
# Find what's using the port
sudo ss -tlnp | grep 6667
# Kill the process if needed
sudo systemctl stop ngircd.service
```

---

## Security Best Practices

1. **Use SSL/TLS** - Enable port 6697 with Let's Encrypt
2. **Strong Operator Password** - Use bcrypt hash (htpasswd)
3. **Firewall Rules** - Only allow IRC ports
4. **Regular Updates** - Keep NixOS and ngircd updated
5. **Monitor Logs** - Watch for abuse: `journalctl -u ngircd.service -f`
6. **Backup Config** - Keep your configuration in git

---

## Additional Features

### Bridge to Discord (Optional)

Use [matterbridge](https://github.com/42wim/matterbridge) to bridge IRC and Discord:

```nix
services.matterbridge = {
  enable = true;
  configPath = "/etc/matterbridge/config.toml";
};
```

### IRC Bouncer (Stay Connected)

Use [ZNC](https://wiki.znc.in/) to stay connected even when offline:

```nix
services.znc = {
  enable = true;
  config = {
    LoadModule = [ "webadmin" ];
    Listener.l = {
      Port = 5000;
      SSL = false;
    };
  };
};
```

---

## Support

- IRC Support Channel: #support on irc.yourdomain.com
- Server Admin: admin@yourdomain.com
- Documentation: https://ngircd.barton.de/documentation

---

## Quick Start Summary

**Server Admin:**
```bash
# 1. Edit irc-public.nix with your details
# 2. Add to flake.nix modules
# 3. Deploy
sudo nixos-rebuild switch --flake .#nixos-btw
# 4. Verify
systemctl status ngircd.service
```

**Users:**
```bash
# Install IRC client (e.g., HexChat)
# Connect to: irc.yourdomain.com:6667
# Join: #general
# Chat!
```

Enjoy your self-hosted IRC community server!