IRC-kosmi-relay/docs/setup/DOCKER_DEPLOYMENT.md

# Docker Deployment Guide

Complete guide for deploying the Kosmi-IRC bridge using Docker.

## Quick Start

```bash
cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml
docker-compose up -d
docker-compose logs -f
```

## Prerequisites

- Docker (20.10+)
- Docker Compose (1.29+)
- A Kosmi room URL
- IRC server access

## Step-by-Step Setup

### 1. Configure the Bridge

Copy `matterbridge.toml.example` to `matterbridge.toml` and update these settings:

```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"

[irc.zeronode]
Server="irc.libera.chat:6697"
Nick="kosmi-relay"
UseTLS=true

[[gateway.inout]]
account="irc.zeronode"
channel="#your-channel"
```

### 2. Build the Docker Image

```bash
docker-compose build
```

This will:
- Use the Go 1.23 Alpine base image
- Install Chromium (used only for email/password authentication)
- Build the Matterbridge binary
- Create a production image

**Build time**: ~5-10 minutes (first time)

### 3. Run the Container

```bash
# Start in detached mode
docker-compose up -d

# Or start with logs visible
docker-compose up
```

### 4. Verify It's Working

```bash
docker-compose logs -f
```

Look for:
```
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages
```

### 5. Test Message Relay

1. **Kosmi --> IRC**: Send a message in your Kosmi room
   - Should appear in IRC as: `[kosmi] <username> message`

2. **IRC --> Kosmi**: Send a message in your IRC channel
   - Should appear in Kosmi as: `[irc] <username> message`

## Docker Commands Reference

### Container Management

```bash
docker-compose up -d            # Start
docker-compose down             # Stop
docker-compose restart          # Restart
docker-compose logs -f          # Follow logs
docker-compose logs --tail=100  # Last 100 lines
docker-compose ps               # Container status
docker-compose exec matterbridge sh  # Shell into container
```

### Updating

```bash
git pull
docker-compose build --no-cache
docker-compose up -d
```

## docker-compose.yml Reference

```yaml
version: '3.8'

services:
  matterbridge:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: kosmi-irc-relay
    restart: unless-stopped
    command: ["-conf", "/app/matterbridge.toml"]
    volumes:
      - ./matterbridge.toml:/app/matterbridge.toml:ro,z
      - ./logs:/app/logs:z
      - ./data:/app/data:z
    environment:
      - TZ=America/New_York
      - MATTERBRIDGE_DATA_DIR=/app/data
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

### Starting Muted

To start with Jackbox announcements suppressed:

```yaml
    command: ["-conf", "/app/matterbridge.toml", "-muted"]
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `TZ` | Timezone for log timestamps | `America/New_York` |
| `MATTERBRIDGE_DATA_DIR` | Directory for persistent data (token cache) | `/app/data` |
| `DEBUG` | Set to `1` for debug logging | `0` |
| `CHROME_BIN` | Path to Chrome binary (set in Dockerfile) | `/usr/bin/chromium-browser` |

Note: `CHROME_BIN` and `CHROME_PATH` are set in the Dockerfile. Chromium is installed in the container for email/password authentication. If you only use anonymous access, Chrome is present but unused.

### Volume Mounts

| Host Path | Container Path | Purpose |
|-----------|----------------|---------|
| `./matterbridge.toml` | `/app/matterbridge.toml` | Configuration (read-only) |
| `./logs` | `/app/logs` | Log files (optional) |
| `./data` | `/app/data` | Persistent data: token cache |

The `./data` volume is important for email/password auth -- it stores the cached JWT so the bot doesn't need to re-authenticate on every restart. See [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md).

## Troubleshooting

### Container Won't Start

```bash
docker-compose logs
```

Common causes:
- TOML syntax error in `matterbridge.toml`
- Missing configuration file
- Port conflict (if webhook port is exposed)

### Kosmi Connection Fails

```bash
# Check connectivity from inside the container
docker-compose exec matterbridge wget -q -O - https://app.kosmi.io > /dev/null && echo "OK"
```

- Verify `RoomURL` is correct
- Enable debug logging (`Debug=true` in the Kosmi config section)

### IRC Connection Fails

```bash
# Test IRC connectivity
docker-compose exec matterbridge nc -zv irc.libera.chat 6697
```

- Verify server address and port
- Check TLS settings
- Try a different nick if the current one is registered/in use

### Messages Not Relaying

1. Confirm both bridges are connected in logs
2. Verify gateway config: Kosmi channel = `"main"`, IRC channel includes `#`
3. Enable debug logging and watch for message routing

### Authentication Issues

If using email/password:
- Delete cached token: `rm ./data/kosmi_token_cache.json`
- Rebuild container: `docker-compose build --no-cache`
- Check Chromium is working: `docker-compose exec matterbridge chromium-browser --version`

## Runtime Operations

### Mute Toggle

Toggle Jackbox announcements without restarting:

```bash
docker kill -s SIGUSR1 kosmi-irc-relay
```

See [MUTE_CONTROL.md](MUTE_CONTROL.md) for details.

### Force Token Refresh

```bash
docker-compose down
rm ./data/kosmi_token_cache.json
docker-compose up -d
```

### View Token Status

```bash
cat ./data/kosmi_token_cache.json | python3 -m json.tool
```

## Resource Usage

The bridge uses a native WebSocket connection, so resource requirements are modest:

- **Memory**: ~50-100MB typical (lower than browser-based approaches)
- **CPU**: Minimal (event-driven, no polling)
- **Network**: WebSocket to Kosmi + IRC connection

### Memory Limits (Optional)

```yaml
services:
  matterbridge:
    mem_limit: 256m
    mem_reservation: 64m
```

## Production Considerations

### Log Rotation

Already configured in `docker-compose.yml`:
```yaml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
```

### Health Check

Add to `docker-compose.yml`:

```yaml
services:
  matterbridge:
    healthcheck:
      test: ["CMD", "pgrep", "-f", "matterbridge"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
```

### Security

- Configuration is mounted read-only (`:ro`)
- Token cache directory has restricted access inside the container
- Credentials in `matterbridge.toml` should be protected: `chmod 600 matterbridge.toml`
- Do not commit `matterbridge.toml` with real credentials to version control

## Further Reading

- [README.md](../../README.md) -- Project overview
- [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md) -- 5-minute quick start
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Jackbox Game Picker setup
- [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) -- Token caching details
- [IRC.md](../IRC.md) -- IRC commands and voting