HyperSpaceOut/IRC-kosmi-relay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
020daea3915f3e52621f140bb59c8fd50c13937d
IRC-kosmi-relay/DOCKER_SETUP_COMPLETE.md
cottongin 020daea391 working v1
2025-10-31 16:17:04 -04:00

8.9 KiB
Raw Blame History

Docker Setup Complete! 🎉

Your Kosmi-IRC bridge is now fully set up with Docker support!

What Was Done

✅ Core Files Created

  1. Dockerfile - Multi-stage build with Chrome/Chromium
  2. docker-compose.yml - Easy deployment configuration
  3. .dockerignore - Optimized build context
  4. DOCKER_DEPLOYMENT.md - Comprehensive deployment guide
  5. DOCKER_QUICKSTART.md - 5-minute quick start guide

✅ Matterbridge Integration

  1. Copied core Matterbridge files:

    • matterbridge.go - Main program
    • gateway/ - Gateway logic
    • internal/ - Internal utilities
    • matterclient/ - Client libraries
    • matterhook/ - Webhook support
    • version/ - Version information

  2. Updated configuration:

    • matterbridge.toml - Complete IRC + Kosmi configuration
    • Added detailed comments and examples

  3. Built successfully:

    • Binary compiles without errors
    • All dependencies resolved
    • Ready for Docker deployment

✅ Bridges Included

  • Kosmi - Your custom bridge with ChromeDP
  • IRC - Full IRC support from Matterbridge
  • Helper utilities - File handling, media download, etc.

Quick Start

1. Configure

Edit matterbridge.toml:

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

[irc.libera]
Server="irc.libera.chat:6667"                   # ← Change this
Nick="kosmi-relay"                              # ← Change this

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

2. Deploy

docker-compose up -d

3. Verify

docker-compose logs -f

Look for:

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

Project Structure

irc-kosmi-relay/
├── Dockerfile                    # Docker build configuration
├── docker-compose.yml            # Docker Compose setup
├── .dockerignore                 # Build optimization
├── matterbridge.toml             # Bridge configuration
├── matterbridge.go               # Main program
│
├── bridge/
│   ├── kosmi/                    # Your Kosmi bridge
│   │   ├── kosmi.go              # Main bridge logic
│   │   ├── chromedp_client.go    # Chrome automation
│   │   └── graphql.go            # GraphQL structures
│   ├── irc/                      # IRC bridge
│   ├── helper/                   # Utility functions
│   ├── config/                   # Configuration types
│   └── bridge.go                 # Bridge interface
│
├── gateway/
│   ├── gateway.go                # Gateway logic
│   ├── bridgemap/                # Bridge registration
│   │   ├── bkosmi.go             # Kosmi registration
│   │   ├── birc.go               # IRC registration
│   │   └── bridgemap.go          # Factory map
│   └── samechannel/              # Same-channel gateway
│
├── cmd/
│   └── test-kosmi/               # Standalone test program
│       └── main.go
│
├── version/
│   └── version.go                # Version information
│
├── internal/                     # Internal utilities
├── matterclient/                 # Client libraries
├── matterhook/                   # Webhook support
│
└── Documentation/
    ├── README.md                 # Main documentation
    ├── DOCKER_QUICKSTART.md      # 5-minute Docker guide
    ├── DOCKER_DEPLOYMENT.md      # Full Docker guide
    ├── QUICKSTART.md             # General quick start
    ├── LESSONS_LEARNED.md        # WebSocket hook insights
    ├── QUICK_REFERENCE.md        # Command reference
    ├── INTEGRATION.md            # Integration guide
    └── CHROMEDP_IMPLEMENTATION.md # ChromeDP details

Docker Features

Multi-Stage Build

  • Stage 1 (Builder): Compiles Go binary
  • Stage 2 (Runtime): Minimal Debian with Chrome

Security

  • ✅ Runs as non-root user (matterbridge)
  • ✅ Read-only configuration mount
  • ✅ Minimal attack surface
  • ✅ No unnecessary packages

Resource Efficiency

  • Image size: ~500MB (includes Chrome)
  • Memory usage: ~200-300MB typical
  • CPU usage: Low (mostly idle)

Reliability

  • ✅ Automatic restart on failure
  • ✅ Health checks (optional)
  • ✅ Log rotation support
  • ✅ Volume mounts for persistence

Testing Checklist

Before deploying to production:

  • Edit matterbridge.toml with your settings
  • Test Kosmi connection: docker-compose up
  • Verify Chrome is working: Check for "✓ WebSocket hook confirmed installed"
  • Test IRC connection: Look for "Successfully connected to IRC"
  • Send test message in Kosmi → verify appears in IRC
  • Send test message in IRC → verify appears in Kosmi
  • Check message format: [Kosmi] <username> and [IRC] <username>
  • Enable debug logging if issues: Debug=true in config
  • Test container restart: docker-compose restart
  • Test automatic reconnection: Disconnect/reconnect network

Common Commands

# Start bridge
docker-compose up -d

# View logs
docker-compose logs -f

# Stop bridge
docker-compose down

# Restart bridge
docker-compose restart

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

# Check status
docker-compose ps

# Execute command in container
docker-compose exec matterbridge sh

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

Deployment Options

Development

# Run with logs visible
docker-compose up

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

Production

# Run in background
docker-compose up -d

# Set up log rotation
# Add to docker-compose.yml:
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

# Monitor logs
docker-compose logs -f --tail=100

High Availability

# Use Docker Swarm
docker swarm init
docker stack deploy -c docker-compose.yml kosmi-relay

# Or Kubernetes
kubectl apply -f kubernetes/

Monitoring

Health Check

# Check if container is running
docker-compose ps

# Check if process is alive
docker-compose exec matterbridge pgrep -f matterbridge

# Check logs for errors
docker-compose logs | grep -i error

Metrics

# Container stats
docker stats kosmi-irc-relay

# Disk usage
docker system df

# Network usage
docker network inspect irc-kosmi-relay_default

Troubleshooting

Quick Fixes

Issue Solution
Container won't start docker-compose logs to see error
Chrome not found docker-compose build --no-cache
Config not loading Check file path in docker-compose.yml
Messages not relaying Enable Debug=true and check logs
High memory usage Add mem_limit: 512m to compose file

Debug Mode

# Enable debug in config
nano matterbridge.toml  # Set Debug=true

# Restart and watch logs
docker-compose restart
docker-compose logs -f | grep -E "DEBUG|ERROR|WARN"

Reset Everything

# Stop and remove containers
docker-compose down

# Remove images
docker-compose down --rmi all

# Rebuild from scratch
docker-compose build --no-cache
docker-compose up -d

Documentation Index

Document Purpose
DOCKER_QUICKSTART.md 5-minute setup guide
DOCKER_DEPLOYMENT.md Complete Docker guide
README.md Project overview
QUICKSTART.md General quick start
LESSONS_LEARNED.md WebSocket hook solution
QUICK_REFERENCE.md Command reference
CHROMEDP_IMPLEMENTATION.md ChromeDP details
INTEGRATION.md Matterbridge integration

Next Steps

  1. ✅ Test the bridge: Send messages both ways
  2. 🔄 Set up monitoring: Add health checks and alerts
  3. 🔄 Configure backups: Backup matterbridge.toml
  4. 🔄 Add more bridges: Discord, Slack, Telegram, etc.
  5. 🔄 Production deployment: Use Docker Swarm or Kubernetes

Support

  • Logs: docker-compose logs -f
  • Debug: Set Debug=true in matterbridge.toml
  • Documentation: See files listed above
  • Test program: ./test-kosmi for standalone testing

Success Indicators

You'll know it's working when you see:

INFO Successfully connected to Kosmi via Chrome
INFO ✓ WebSocket hook confirmed installed
INFO Status: WebSocket connection intercepted
INFO Successfully connected to IRC
INFO Gateway(s) started successfully. Now relaying messages

And messages flow both ways:

  • Kosmi → IRC: [Kosmi] <username> message
  • IRC → Kosmi: [IRC] <username> message

Congratulations! 🎉

Your Kosmi-IRC bridge is ready to use! The Docker setup provides:

  • ✅ Easy deployment
  • ✅ Automatic restarts
  • ✅ Isolated environment
  • ✅ Production-ready configuration
  • ✅ Simple updates and maintenance

Enjoy your bridge! 🚀

Reference in New Issue View Git Blame Copy Permalink