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

# Docker Quick Start -- 5 Minutes to Running Bridge

Get your Kosmi-IRC bridge running in Docker in 5 minutes.

## Prerequisites

- Docker installed
- Docker Compose installed
- A Kosmi room URL
- An IRC channel

## Steps

### 1. Edit Configuration (2 minutes)

```bash
cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml
```

Change these 3 things:

```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"  # <-- Your Kosmi room

[irc.zeronode]
Server="irc.libera.chat:6697"                   # <-- Your IRC server
Nick="kosmi-relay"                               # <-- Your bot's nickname

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

### 2. Build and Run (2 minutes)

```bash
docker-compose up -d
```

### 3. Check It's Working (1 minute)

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

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

### 4. Test It

- Send a message in Kosmi --> should appear in IRC
- Send a message in IRC --> should appear in Kosmi

## Common Commands

```bash
# View logs
docker-compose logs -f

# Stop bridge
docker-compose down

# Restart bridge
docker-compose restart

# Rebuild after code changes
docker-compose build && docker-compose up -d
```

## Troubleshooting

### "Connection failed"

1. Check your configuration:
   ```bash
   grep -E "RoomURL|Server|channel" matterbridge.toml
   ```

2. Enable debug logging:
   - Edit `matterbridge.toml`: Set `Debug=true` under the appropriate bridge section
   - Restart: `docker-compose restart`
   - Watch logs: `docker-compose logs -f`

### "Messages not relaying"

1. Check both bridges are connected:
   ```bash
   docker-compose logs | grep -i "connected\|succeeded"
   ```

2. Verify channel names:
   - Kosmi channel must be `"main"`
   - IRC channel must include `#` (e.g., `"#your-channel"`)

## Persistent Token Cache

If using email/password authentication, the JWT is cached in `./data/` which is mounted into the container. This survives container rebuilds and restarts. See [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) for details.

## Need More Help?

- Full Docker guide: [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md)
- Quick reference: [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
- IRC commands: [IRC.md](../IRC.md)