IRC-kosmi-relay/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

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

Quick Start

# 1. Edit configuration
nano matterbridge.toml

# 2. Build and run
docker-compose up -d

# 3. View logs
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

Edit matterbridge.toml and update these settings:

[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"  # ← Change this
Debug=false

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

[[gateway.inout]]
account="kosmi.hyperspaceout"
channel="main"

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

2. Build the Docker Image

docker-compose build

This will:

• Install Chrome/Chromium in the container
• Build the Matterbridge binary with Kosmi support
• Create an optimized 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

# Check container status
docker-compose ps

# View logs
docker-compose logs -f matterbridge

# Look for these messages:
# INFO Successfully connected to Kosmi via Chrome
# INFO Successfully connected to IRC
# INFO Gateway(s) started successfully

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

# Start the bridge
docker-compose up -d

# Stop the bridge
docker-compose down

# Restart the bridge
docker-compose restart

# View logs
docker-compose logs -f

# View last 100 lines of logs
docker-compose logs --tail=100

# Check container status
docker-compose ps

# Execute commands in running container
docker-compose exec matterbridge sh

Debugging

# Enable debug logging (edit docker-compose.yml first)
# Set Debug=true in matterbridge.toml, then:
docker-compose restart

# Check Chrome is installed
docker-compose exec matterbridge which chromium

# Check configuration
docker-compose exec matterbridge cat /app/matterbridge.toml

# Test connectivity
docker-compose exec matterbridge ping -c 3 app.kosmi.io
docker-compose exec matterbridge ping -c 3 irc.libera.chat

Updating

# Pull latest code
git pull

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

# Restart with new image
docker-compose up -d

Configuration Options

docker-compose.yml

services:
  matterbridge:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: kosmi-irc-relay
    restart: unless-stopped
    volumes:
      - ./matterbridge.toml:/app/matterbridge.toml:ro
      - ./logs:/app/logs
    environment:
      - CHROME_BIN=/usr/bin/chromium
      - CHROME_PATH=/usr/bin/chromium
      - TZ=America/New_York  # ← Change to your timezone
    security_opt:
      - seccomp:unconfined  # Required for Chrome

Environment Variables

Variable	Description	Default
CHROME_BIN	Path to Chrome binary	/usr/bin/chromium
CHROME_PATH	Chrome executable path	/usr/bin/chromium
TZ	Timezone for logs	America/New_York
DEBUG	Enable debug logging	0

Volume Mounts

Host Path	Container Path	Purpose
./matterbridge.toml	/app/matterbridge.toml	Configuration file (read-only)
./logs	/app/logs	Log files (optional)

Troubleshooting

Container Won't Start

Check logs:

docker-compose logs

Common issues:

• Configuration file syntax error
• Missing matterbridge.toml
• Port already in use

Solution:

# Validate TOML syntax
docker run --rm -v $(pwd)/matterbridge.toml:/config.toml alpine sh -c "apk add --no-cache go && go install github.com/pelletier/go-toml/cmd/tomll@latest && tomll /config.toml"

# Check if file exists
ls -la matterbridge.toml

Chrome/Chromium Not Found

Symptoms:

ERROR Chrome binary not found

Solution:

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

# Verify Chrome is installed
docker-compose run --rm matterbridge which chromium

WebSocket Connection Failed

Symptoms:

ERROR Failed to connect to Kosmi
ERROR WebSocket connection failed

Solution:

# Test network connectivity
docker-compose exec matterbridge ping -c 3 app.kosmi.io

# Check if room URL is correct
docker-compose exec matterbridge cat /app/matterbridge.toml | grep RoomURL

# Enable debug logging
# Edit matterbridge.toml: Debug=true
docker-compose restart

IRC Connection Failed

Symptoms:

ERROR Failed to connect to IRC
ERROR Connection refused

Solution:

# Test IRC connectivity
docker-compose exec matterbridge nc -zv irc.libera.chat 6667

# Check IRC configuration
docker-compose exec matterbridge cat /app/matterbridge.toml | grep -A 10 "\[irc\]"

# Verify nickname isn't already in use
# Try changing Nick in matterbridge.toml

Messages Not Relaying

Symptoms:

• Container running
• Both bridges connected
• But messages don't appear

Solution:

# Enable debug logging
# Edit matterbridge.toml: Debug=true
docker-compose restart

# Watch logs for message flow
docker-compose logs -f | grep -E "Received|Sending|Forwarding"

# Verify gateway configuration
docker-compose exec matterbridge cat /app/matterbridge.toml | grep -A 20 "\[\[gateway\]\]"

# Check channel names match exactly
# Kosmi channel should be "main"
# IRC channel should include # (e.g., "#your-channel")

High Memory Usage

Symptoms:

• Container using >500MB RAM
• System slowdown

Solution:

# Add memory limits to docker-compose.yml
services:
  matterbridge:
    mem_limit: 512m
    mem_reservation: 256m

# Restart
docker-compose up -d

Permission Denied Errors

Symptoms:

ERROR Permission denied writing to /app/logs

Solution:

# Create logs directory with correct permissions
mkdir -p logs
chmod 777 logs

# Or run container as root (not recommended)
# Edit docker-compose.yml:
# user: root

Production Deployment

Using Docker Swarm

# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.yml kosmi-relay

# Check status
docker stack services kosmi-relay

# View logs
docker service logs -f kosmi-relay_matterbridge

Using Kubernetes

Create kosmi-relay.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kosmi-irc-relay
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kosmi-irc-relay
  template:
    metadata:
      labels:
        app: kosmi-irc-relay
    spec:
      containers:
      - name: matterbridge
        image: kosmi-irc-relay:latest
        volumeMounts:
        - name: config
          mountPath: /app/matterbridge.toml
          subPath: matterbridge.toml
        env:
        - name: CHROME_BIN
          value: /usr/bin/chromium
        - name: TZ
          value: America/New_York
        securityContext:
          capabilities:
            add:
            - SYS_ADMIN  # Required for Chrome
      volumes:
      - name: config
        configMap:
          name: matterbridge-config

Deploy:

kubectl create configmap matterbridge-config --from-file=matterbridge.toml
kubectl apply -f kosmi-relay.yaml

Monitoring

Health Check

Add to docker-compose.yml:

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

Prometheus Metrics

Matterbridge doesn't expose Prometheus metrics by default, but you can monitor:

# Container metrics
docker stats kosmi-irc-relay

# Log-based monitoring
docker-compose logs -f | grep -E "ERROR|WARN"

Backup and Restore

# Backup configuration
cp matterbridge.toml matterbridge.toml.backup

# Backup logs
tar -czf logs-$(date +%Y%m%d).tar.gz logs/

# Restore configuration
cp matterbridge.toml.backup matterbridge.toml
docker-compose restart

Security Best Practices

1. Run as non-root user (already configured in Dockerfile)
2. Use read-only configuration mount
3. Limit container resources
4. Keep Docker images updated
5. Use secrets for sensitive data (e.g., IRC passwords)

Using Docker Secrets

# Create secret
echo "your_irc_password" | docker secret create irc_password -

# Update docker-compose.yml
services:
  matterbridge:
    secrets:
      - irc_password

secrets:
  irc_password:
    external: true

Performance Tuning

Resource Limits

services:
  matterbridge:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Chrome Optimization

Add to docker-compose.yml:

services:
  matterbridge:
    environment:
      - CHROME_FLAGS=--disable-dev-shm-usage --no-sandbox --disable-setuid-sandbox

Next Steps

• ✅ Bridge is running in Docker
• 🔄 Set up monitoring and alerts
• 🔄 Configure log rotation
• 🔄 Set up automatic backups
• 🔄 Add more bridges (Discord, Slack, etc.)

Getting Help

• Check logs: docker-compose logs -f
• Enable debug: Set Debug=true in matterbridge.toml
• Review LESSONS_LEARNED.md for common issues
• Check QUICK_REFERENCE.md for troubleshooting tips

Example: Complete Setup

# 1. Clone repository
git clone <your-repo> kosmi-irc-relay
cd kosmi-irc-relay

# 2. Edit configuration
nano matterbridge.toml
# Update RoomURL, IRC server, channel

# 3. Build and start
docker-compose up -d

# 4. Watch logs
docker-compose logs -f

# 5. Test by sending messages in both Kosmi and IRC

# 6. If issues, enable debug
nano matterbridge.toml  # Set Debug=true
docker-compose restart
docker-compose logs -f

That's it! Your Kosmi-IRC bridge is now running in Docker! 🎉