Files

docs: comprehensive documentation overhaul

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>

2026-05-12 22:01:25 -04:00

2.3 KiB

Raw Blame History

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)

cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml

Change these 3 things:

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

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

[[gateway.inout]]
account="irc.zeronode"
channel="#your-channel"                          # <-- Your IRC channel

2. Build and 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
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages

4. Test It

Send a message in Kosmi --> should appear in IRC
Send a message in IRC --> should appear in Kosmi

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"

Check your configuration:

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

Enable debug logging:
- Edit matterbridge.toml: Set Debug=true under the appropriate bridge section
- Restart: docker-compose restart
- Watch logs: docker-compose logs -f

"Messages not relaying"

Check both bridges are connected:

docker-compose logs | grep -i "connected\|succeeded"

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

Persistent Token Cache

If using email/password authentication, the JWT is cached in ./data/ which is mounted into the container. This survives container rebuilds and restarts. See TOKEN_PERSISTENCE.md for details.

Need More Help?

Full Docker guide: DOCKER_DEPLOYMENT.md
Quick reference: QUICK_REFERENCE.md
IRC commands: IRC.md

2.3 KiB Raw Blame History