IRC-kosmi-relay/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)

Open matterbridge.toml and change these 3 things:

[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"  # ← Your Kosmi room

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

[[gateway.inout]]
account="irc.libera"
channel="#your-channel"                         # ← Your IRC channel

2. Build & Run (2 minutes)

docker-compose up -d

3. Check It's Working (1 minute)

docker-compose logs -f

Look for:

INFO Successfully connected to Kosmi via Chrome
INFO Successfully connected to IRC
INFO Gateway(s) started successfully

4. Test It!

• Send a message in Kosmi → should appear in IRC
• Send a message in IRC → should appear in Kosmi

That's It! 🎉

Your bridge is running!

Common Commands

# 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:

   cat matterbridge.toml | grep -E "RoomURL|Server|channel"
   

2. Enable debug logging:

   • Edit matterbridge.toml: Set Debug=true
   • Restart: docker-compose restart
   • Watch logs: docker-compose logs -f

"Chrome not found"

# Rebuild image
docker-compose build --no-cache
docker-compose up -d

"Messages not relaying"

1. Check both bridges are connected:

   docker-compose logs | grep -i "connected"
   

2. Verify channel names:

   • Kosmi channel must be "main"
   • IRC channel must include # (e.g., "#your-channel")

Need More Help?

• Full guide: See DOCKER_DEPLOYMENT.md
• Troubleshooting: See QUICK_REFERENCE.md
• Implementation details: See LESSONS_LEARNED.md

Example Output (Success)

INFO[...] Starting Matterbridge
INFO[...] Launching headless Chrome for Kosmi connection
INFO[...] Injecting WebSocket interceptor (runs before page load)...
INFO[...] ✓ WebSocket hook confirmed installed
INFO[...] Status: WebSocket connection intercepted
INFO[...] Successfully connected to Kosmi via Chrome
INFO[...] Connecting to IRC server irc.libera.chat:6667
INFO[...] Successfully connected to IRC
INFO[...] Gateway(s) started successfully. Now relaying messages

Now send a test message and watch it relay! 🚀