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

82
docs/setup/DOCKER_QUICKSTART.md
View File

@@ -1,6 +1,6 @@
# Docker Quick Start - 5 Minutes to Running Bridge
# Docker Quick Start -- 5 Minutes to Running Bridge
Get your Kosmi-IRC bridge running in Docker in 5 minutes!
Get your Kosmi-IRC bridge running in Docker in 5 minutes.
## Prerequisites
@@ -13,22 +13,27 @@ Get your Kosmi-IRC bridge running in Docker in 5 minutes!
### 1. Edit Configuration (2 minutes)
Open `matterbridge.toml` and change these 3 things:
```bash
cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml
```
Change these 3 things:
```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM" # ← Your Kosmi room
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM" # <-- Your Kosmi room
[irc.libera]
Server="irc.libera.chat:6667" # ← Your IRC server
Nick="kosmi-relay" # ← Your bot's nickname
[irc.zeronode]
Server="irc.libera.chat:6697" # <-- Your IRC server
Nick="kosmi-relay" # <-- Your bot's nickname
[[gateway.inout]]
account="irc.libera"
channel="#your-channel" # ← Your IRC channel
account="irc.zeronode"
channel="#your-channel" # <-- Your IRC channel
```
### 2. Build & Run (2 minutes)
### 2. Build and Run (2 minutes)
```bash
docker-compose up -d
@@ -42,19 +47,15 @@ docker-compose logs -f
Look for:
```
INFO Successfully connected to Kosmi via Chrome
INFO Successfully connected to IRC
INFO Gateway(s) started successfully
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages
```
### 4. Test It!
### 4. Test It
- Send a message in Kosmi → should appear in IRC
- Send a message in IRC → should appear in Kosmi
## That's It! 🎉
Your bridge is running!
- Send a message in Kosmi --> should appear in IRC
- Send a message in IRC --> should appear in Kosmi
## Common Commands
@@ -78,52 +79,31 @@ docker-compose build && docker-compose up -d
1. Check your configuration:
```bash
cat matterbridge.toml | grep -E "RoomURL|Server|channel"
grep -E "RoomURL|Server|channel" matterbridge.toml
```
2. Enable debug logging:
- Edit `matterbridge.toml`: Set `Debug=true`
- Edit `matterbridge.toml`: Set `Debug=true` under the appropriate bridge section
- Restart: `docker-compose restart`
- Watch logs: `docker-compose logs -f`
### "Chrome not found"
```bash
# Rebuild image
docker-compose build --no-cache
docker-compose up -d
```
### "Messages not relaying"
1. Check both bridges are connected:
```bash
docker-compose logs | grep -i "connected"
docker-compose logs | grep -i "connected\|succeeded"
```
2. 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](TOKEN_PERSISTENCE.md) for details.
## Need More Help?
- Full guide: See `DOCKER_DEPLOYMENT.md`
- Troubleshooting: See `QUICK_REFERENCE.md`
- Implementation details: See `LESSONS_LEARNED.md`
## Example Output (Success)
```
INFO[...] Starting Matterbridge
INFO[...] Launching headless Chrome for Kosmi connection
INFO[...] Injecting WebSocket interceptor (runs before page load)...
INFO[...] ✓ WebSocket hook confirmed installed
INFO[...] Status: WebSocket connection intercepted
INFO[...] Successfully connected to Kosmi via Chrome
INFO[...] Connecting to IRC server irc.libera.chat:6667
INFO[...] Successfully connected to IRC
INFO[...] Gateway(s) started successfully. Now relaying messages
```
Now send a test message and watch it relay! 🚀
- Full Docker guide: [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md)
- Quick reference: [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
- IRC commands: [IRC.md](../IRC.md)