docs: add README with setup instructions and docker-compose.yml

Made-with: Cursor

README.md

@@ -0,0 +1,108 @@
+# owncast-irc-bridge
+
+Bidirectional chat bridge between [Owncast](https://owncast.online/) and IRC. Messages sent in your Owncast chat appear in an IRC channel and vice versa.
+
+## Quick Start (Docker Compose)
+
+**1. Create your config file**
+
+```bash
+cp config.example.toml config.toml
+```
+
+Edit `config.toml` with your IRC server/channel and Owncast URL.
+
+**2. Get an Owncast access token**
+
+In your Owncast admin panel, go to **Integrations > Access Tokens** and create a token with "send messages" permission.
+
+**3. Set the token**
+
+```bash
+export OWNCAST_ACCESS_TOKEN="your-token-here"
+```
+
+Or create a `.env` file (git-ignored):
+
+```
+OWNCAST_ACCESS_TOKEN=your-token-here
+```
+
+**4. Configure the Owncast webhook**
+
+In your Owncast admin, go to **Integrations > Webhooks** and add a webhook pointing to:
+
+```
+http://<bridge-host>:9078/webhook
+```
+
+Select the events: **Chat Message**, **Stream Started**, **Stream Stopped**.
+
+**5. Run it**
+
+```bash
+docker compose up -d
+```
+
+Check logs:
+
+```bash
+docker compose logs -f
+```
+
+## Running Without Docker
+
+Requires Rust 1.75+.
+
+```bash
+cargo build --release
+export OWNCAST_ACCESS_TOKEN="your-token-here"
+./target/release/owncast-irc-bridge --config config.toml
+```
+
+## Configuration
+
+See [`config.example.toml`](config.example.toml) for all options. The only required sections are `[irc]` (with `server` and `channel`) and `[owncast]` (with `url`). Everything else has defaults.
+
+| Section | Key | Default | Description |
+|---------|-----|---------|-------------|
+| `irc` | `server` | *(required)* | IRC server hostname |
+| `irc` | `port` | `6667` | IRC server port |
+| `irc` | `tls` | `false` | Use TLS for IRC |
+| `irc` | `nick` | `owncast-bridge` | IRC nickname |
+| `irc` | `channel` | *(required)* | IRC channel to join |
+| `owncast` | `url` | *(required)* | Owncast instance URL |
+| `owncast` | `webhook_port` | `9078` | Port the webhook server listens on |
+| `owncast` | `websocket_enabled` | `false` | Also connect via WebSocket (redundant with webhook, useful as fallback) |
+| `owncast` | `health_poll_interval_secs` | `30` | How often to poll Owncast status |
+| `bridge` | `irc_prefix` | `[IRC]` | Prefix for IRC messages in Owncast |
+| `bridge` | `owncast_prefix` | `[OC]` | Prefix for Owncast messages in IRC |
+| `control` | `socket_path` | `/tmp/owncast-irc-bridge.sock` | Unix socket for `bridge-ctl` |
+
+The access token is always read from the `OWNCAST_ACCESS_TOKEN` environment variable (not the config file).
+
+## Runtime Control
+
+Use `bridge-ctl` to interact with a running bridge:
+
+```bash
+bridge-ctl status              # Show bridge status as JSON
+bridge-ctl irc reconnect       # Reconnect to IRC
+bridge-ctl owncast reconnect   # Reconnect to Owncast
+bridge-ctl quit                # Shut down the bridge
+```
+
+Inside Docker:
+
+```bash
+docker compose exec bridge bridge-ctl status
+```
+
+## How It Works
+
+- **Owncast → IRC:** Owncast sends webhook events to the bridge. The bridge formats the message and sends it to IRC via PRIVMSG.
+- **IRC → Owncast:** The bridge listens for PRIVMSG in the configured channel and posts to Owncast via the integration API.
+- **Deduplication:** If both webhook and WebSocket are enabled, duplicate messages are detected by ID and dropped.
+- **Echo suppression:** Messages the bridge itself sent are recognized and not re-bridged.
+- **Stream events:** Stream start/stop events are announced in IRC.
+- **Health polling:** The bridge polls Owncast's `/api/status` endpoint and announces state changes in IRC.