HyperSpaceOut/IRC-kosmi-relay
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive documentation overhaul

Browse Source 
Rewrite README.md and all setup guides to reflect the current native
GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket
interception descriptions). Add new docs/IRC.md with complete IRC command
reference, vote syntax, and ticker symbol table.

Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move
historical development notes from docs/ root into docs/archive/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cottongin
2026-05-12 22:01:25 -04:00
parent 4188ae29af
commit c88b75f30d
57 changed files with 4530 additions and 1994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

515
docs/setup/DOCKER_DEPLOYMENT.md
View File

@@ -5,13 +5,9 @@ Complete guide for deploying the Kosmi-IRC bridge using Docker.
## Quick Start
```bash
# 1. Edit configuration
cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml
# 2. Build and run
docker-compose up -d
# 3. View logs
docker-compose logs -f
```
@@ -26,24 +22,20 @@ docker-compose logs -f
### 1. Configure the Bridge
Edit `matterbridge.toml` and update these settings:
Copy `matterbridge.toml.example` to `matterbridge.toml` and update these settings:
```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM" # ← Change this
Debug=false
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"
[irc.libera]
Server="irc.libera.chat:6667" # ← Change to your IRC server
Nick="kosmi-relay" # ← Change your bot's nickname
[irc.zeronode]
Server="irc.libera.chat:6697"
Nick="kosmi-relay"
UseTLS=true
[[gateway.inout]]
account="kosmi.hyperspaceout"
channel="main"
[[gateway.inout]]
account="irc.libera"
channel="#your-channel" # ← Change to your IRC channel
account="irc.zeronode"
channel="#your-channel"
```
### 2. Build the Docker Image
@@ -53,9 +45,10 @@ docker-compose build
```
This will:
- Install Chrome/Chromium in the container
- Build the Matterbridge binary with Kosmi support
- Create an optimized production image
- 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)
@@ -72,89 +65,51 @@ docker-compose up
### 4. Verify It's Working
```bash
# Check container status
docker-compose ps
docker-compose logs -f
```
# 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
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`
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`
2. **IRC --> Kosmi**: Send a message in your IRC channel
- Should appear in Kosmi as: `[irc] <username> message`
## Docker Commands Reference
### Container Management
```bash
# 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
```bash
# 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
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
```bash
# 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
## docker-compose.yml Reference
```yaml
version: '3.8'
services:
matterbridge:
build:
@@ -162,241 +117,154 @@ services:
dockerfile: Dockerfile
container_name: kosmi-irc-relay
restart: unless-stopped
command: ["-conf", "/app/matterbridge.toml"]
volumes:
- ./matterbridge.toml:/app/matterbridge.toml:ro
- ./logs:/app/logs
- ./matterbridge.toml:/app/matterbridge.toml:ro,z
- ./logs:/app/logs:z
- ./data:/app/data:z
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
- 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:
```yaml
command: ["-conf", "/app/matterbridge.toml", "-muted"]
```
### 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` |
| `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 file (read-only) |
| `./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](TOKEN_PERSISTENCE.md).
## Troubleshooting
### Container Won't Start
**Check logs**:
```bash
docker-compose logs
```
**Common issues**:
- Configuration file syntax error
- Missing `matterbridge.toml`
- Port already in use
Common causes:
- TOML syntax error in `matterbridge.toml`
- Missing configuration file
- Port conflict (if webhook port is exposed)
### Kosmi Connection Fails
**Solution**:
```bash
# 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
# Check connectivity from inside the container
docker-compose exec matterbridge wget -q -O - https://app.kosmi.io > /dev/null && echo "OK"
```
### Chrome/Chromium Not Found
- Verify `RoomURL` is correct
- Enable debug logging (`Debug=true` in the Kosmi config section)
**Symptoms**:
```
ERROR Chrome binary not found
```
### IRC Connection Fails
**Solution**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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
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
**Symptoms**:
- Container running
- Both bridges connected
- But messages don't appear
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:
**Solution**:
```bash
# 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")
docker kill -s SIGUSR1 kosmi-irc-relay
```
### High Memory Usage
See [MUTE_CONTROL.md](MUTE_CONTROL.md) for details.
**Symptoms**:
- Container using >500MB RAM
- System slowdown
### Force Token Refresh
**Solution**:
```bash
# Add memory limits to docker-compose.yml
services:
matterbridge:
mem_limit: 512m
mem_reservation: 256m
# Restart
docker-compose down
rm ./data/kosmi_token_cache.json
docker-compose up -d
```
### Permission Denied Errors
**Symptoms**:
```
ERROR Permission denied writing to /app/logs
```
**Solution**:
```bash
# 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
### View Token Status
```bash
# 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
cat ./data/kosmi_token_cache.json | python3 -m json.tool
```
### Using Kubernetes
## Resource Usage
Create `kosmi-relay.yaml`:
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)
```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
services:
matterbridge:
mem_limit: 256m
mem_reservation: 64m
```
Deploy:
```bash
kubectl create configmap matterbridge-config --from-file=matterbridge.toml
kubectl apply -f kosmi-relay.yaml
## Production Considerations
### Log Rotation
Already configured in `docker-compose.yml`:
```yaml
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```
### Monitoring
#### Health Check
### Health Check
Add to `docker-compose.yml`:
@@ -408,127 +276,20 @@ services:
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
start_period: 30s
```
#### Prometheus Metrics
### Security
Matterbridge doesn't expose Prometheus metrics by default, but you can monitor:
- 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
```bash
# Container metrics
docker stats kosmi-irc-relay
# Log-based monitoring
docker-compose logs -f | grep -E "ERROR|WARN"
```
### Backup and Restore
```bash
# 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
```bash
# 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
```yaml
services:
matterbridge:
deploy:
resources:
limits:
cpus: '1.0'
memory: 512M
reservations:
cpus: '0.5'
memory: 256M
```
### Chrome Optimization
Add to `docker-compose.yml`:
```yaml
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
```bash
# 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! 🎉
## Further Reading
- [README.md](../../README.md) -- Project overview
- [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md) -- 5-minute quick start
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Jackbox Game Picker setup
- [TOKEN_PERSISTENCE.md](TOKEN_PERSISTENCE.md) -- Token caching details
- [IRC.md](../IRC.md) -- IRC commands and voting