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

Docker Deployment Guide

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

Quick Start

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:

[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

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

# Start in detached mode
docker-compose up -d

# Or start with logs visible
docker-compose up

4. Verify It's Working

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

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

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

docker-compose.yml Reference

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:

    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.

Troubleshooting

Container Won't Start

docker-compose logs

Common causes:

• TOML syntax error in matterbridge.toml
• Missing configuration file
• Port conflict (if webhook port is exposed)

Kosmi Connection Fails

# 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

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

docker kill -s SIGUSR1 kosmi-irc-relay

See MUTE_CONTROL.md for details.

Force Token Refresh

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

View Token Status

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)

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

Production Considerations

Log Rotation

Already configured in docker-compose.yml:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Health Check

Add to docker-compose.yml:

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 -- Project overview
• DOCKER_QUICKSTART.md -- 5-minute quick start
• JACKBOX_INTEGRATION.md -- Jackbox Game Picker setup
• TOKEN_PERSISTENCE.md -- Token caching details
• IRC.md -- IRC commands and voting