From 38da6cb2bd1252064f63f2a74aa6b3ade9f3d05d Mon Sep 17 00:00:00 2001 From: J3vb Date: Fri, 3 Apr 2026 14:36:10 +0200 Subject: [PATCH] docs: add Docker + LiveKit deployment guide - deployment.md: new Docker section with quick-start, config.yaml notes, data persistence, upgrade, and LiveKit reference - livekit-setup.md: new Docker section with .env / livekit.yaml setup, node_ip explanation, and firewall table; companion process section retitled for clarity --- docs/deployment.md | 69 +++++++++++++++++++++++++++++++++++++++++++ docs/livekit-setup.md | 55 ++++++++++++++++++++++++++++++++-- 2 files changed, 122 insertions(+), 2 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 6b2c93c2..ec5fb632 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,6 +31,75 @@ Alternatively, download a pre-built binary from GitHub Releases: - **Windows**: `chatserver.exe` - **Linux**: `chatserver-linux-amd64.tar.gz` (extract to get `chatserver`) +## Docker (Linux) + +The easiest way to run OwnCord on Linux. Includes the chat server and LiveKit voice/video as separate containers on a shared internal network. + +### Prerequisites + +- Docker Engine 24+ and Docker Compose v2 +- Ports available: `8443` (chat), `7880-7881` TCP, `50000-60000` UDP (LiveKit media) + +### Quick Start + +```bash +cd Server + +# 1. Create your secrets file +cp .env.example .env +# Edit .env — set LIVEKIT_API_KEY and LIVEKIT_API_SECRET (secret must be 32+ chars) + +# 2. Create your LiveKit config +cp livekit.yaml.example livekit.yaml +# Edit livekit.yaml — set node_ip to your server's public IP, and paste the same key/secret + +# 3. Create a minimal config.yaml for OwnCord (server name, TLS, etc.) +# Leave voice.livekit_url and voice.livekit_binary unset — compose injects these via env vars + +# 4. Start +docker compose up -d +``` + +On first start OwnCord creates its database and writes defaults into `/app/data`. Navigate to `https://:8443/admin` to create the Owner account. + +### config.yaml for Docker + +You do **not** need to set `voice.livekit_api_key`, `voice.livekit_api_secret`, or `voice.livekit_binary` in your `config.yaml` when using Docker — these are injected via environment variables from `.env`. Set everything else as normal: + +```yaml +server: + name: "My OwnCord" + port: 8443 + +voice: + livekit_url: "ws://livekit:7880" # Docker service DNS — do not change + quality: "medium" + +tls: + mode: "self_signed" # or "acme" / "manual" for production +``` + +### Data Persistence + +The `owncord-data` Docker volume maps to `/app/data` inside the container. This holds the SQLite database, TLS certs, uploads, and backups. It persists across container restarts and upgrades. + +To back up, use the admin backup endpoint as normal — backups land in `/app/data/backups/` which is part of the named volume. + +### Upgrading + +```bash +docker compose pull +docker compose up -d +``` + +The named volume is preserved — no data loss. + +### LiveKit in Docker + +LiveKit runs as its own container (`livekit/livekit-server:v1`) and is **not** managed by OwnCord's companion-process system. Leave `voice.livekit_binary` unset. See [LiveKit Setup — Docker](livekit-setup.md#docker) for details. + +--- + ## First Run Behavior When `chatserver.exe` starts for the first time: diff --git a/docs/livekit-setup.md b/docs/livekit-setup.md index 1842990e..9fcdbd60 100644 --- a/docs/livekit-setup.md +++ b/docs/livekit-setup.md @@ -2,11 +2,62 @@ LiveKit is an open-source SFU (Selective Forwarding Unit) that handles real-time voice and video. OwnCord uses it instead of rolling its own WebRTC stack -- LiveKit handles all the hard parts (DTLS, ICE, codec negotiation, simulcast) while OwnCord manages permissions, state, and room lifecycle. +There are two ways to run LiveKit alongside OwnCord: + +| Method | Best for | LiveKit managed by | +|--------|----------|--------------------| +| **Docker Compose** | Linux servers | Docker (separate container) | +| **Companion process** | Windows / bare-metal Linux | OwnCord (auto-start) | + --- -## 1. Get the LiveKit Binary +## Docker -Download `livekit-server` for Windows from one of: +When running OwnCord via `docker compose`, LiveKit runs as a separate container on the same internal network. OwnCord reaches it at `ws://livekit:7880` via Docker's internal DNS — no port forwarding needed between containers. + +### Setup + +1. **Edit `.env`** (in `Server/`) — set `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`: + + ``` + LIVEKIT_API_KEY=my-unique-key + LIVEKIT_API_SECRET=my-secret-at-least-32-characters-long + ``` + +2. **Edit `livekit.yaml`** (copy from `livekit.yaml.example`) — use the same key/secret and set your public IP: + + ```yaml + port: 7880 + rtc: + tcp_port: 7881 + port_range_start: 50000 + port_range_end: 60000 + node_ip: "YOUR_SERVER_PUBLIC_IP" # required for remote clients + keys: + my-unique-key: my-secret-at-least-32-characters-long + logging: + level: info + ``` + +3. **Leave `voice.livekit_binary` unset** in your `config.yaml`. The `voice.livekit_url` should be `ws://livekit:7880` (Docker DNS). + +4. **Open firewall ports** on your host: + + | Port | Protocol | Purpose | + |------|----------|---------| + | `7880` | TCP | LiveKit signaling | + | `7881` | TCP | TCP fallback for WebRTC | + | `50000-60000` | UDP | WebRTC media | + +> **`node_ip` is required** for remote clients. Without it, LiveKit advertises internal Docker IP addresses as ICE candidates, which are unreachable from the internet. If your cloud VM has a metadata service (AWS, GCP, DigitalOcean) you can use `use_external_ip: true` instead. + +--- + +## Companion Process (Windows / bare-metal Linux) + +### 1. Get the LiveKit Binary + +Download `livekit-server` for your platform from one of: - **GitHub releases**: - Grab the `livekit-server_*_windows_amd64.zip` asset