From b3bcb283ee0bcf7cb77dfb0791427de2c457d8ac Mon Sep 17 00:00:00 2001 From: jevb Date: Wed, 18 Mar 2026 17:56:03 +0100 Subject: [PATCH] docs: rewrite README with current features, architecture, and config --- README.md | 238 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 190 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 8df7362c..48005db5 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,87 @@ # OwnCord -Self-hosted Windows chat platform with voice, video, and -an admin panel. +A self-hosted Windows chat platform with real-time messaging, +voice/video, file sharing, and a web admin panel. Run your own +server and keep everything under your control. ## Features -- Real-time text chat with threads and reactions -- Voice and video channels (WebRTC) +### Chat + +- Real-time text messaging over WebSocket +- Message editing, deletion, and replies +- Emoji reactions with per-message counts +- Typing indicators +- Full-text message search (SQLite FTS5) +- Pinned messages per channel +- Rich link previews with Open Graph metadata +- YouTube embed support with cached titles + +### Voice & Video + +- Voice channels with WebRTC (Pion SFU) +- Mute, deafen, camera, and screenshare controls +- Built-in TURN/STUN server (no external dependencies) +- Configurable audio quality (low/medium/high) + +### Channels & Organization + +- Text and voice channels organized by categories +- Create, edit, delete, and reorder channels +- Unread message indicators +- Quick channel switcher (Ctrl+K) + +### File Sharing + +- Drag-and-drop and clipboard paste uploads +- Inline image previews with persistent caching (IndexedDB) +- File download with native save dialog +- Configurable max upload size + +### Users & Permissions + +- Invite-only registration with invite codes - Role-based permissions with custom roles -- File sharing with inline previews -- Full-text message search -- Web-based admin panel -- Invite-only registration -- TLS encryption (self-signed or custom cert) +- Member list with online/offline presence +- User profiles with status (online, idle, dnd, offline) + +### Administration + +- Web-based admin panel at `/admin` +- User management (ban, kick, role assignment) +- Server update checker (GitHub Releases integration) +- Structured request logging + +### Security + +- TLS encryption (self-signed, Let's Encrypt, or custom cert) +- Trust-on-first-use certificate pinning in the client +- Ed25519-signed client auto-updates +- Rate limiting on all endpoints +- CSRF protection and security headers + +### Desktop Client + +- Native Windows app built with Tauri v2 +- System tray integration +- In-app auto-update with progress notification +- Credential storage via Windows Credential Manager +- Custom emoji picker and soundboard ## Quick Start -1. Download the latest release from GitHub Releases -2. Run `chatserver.exe` -- generates `config.yaml` on first run +1. Download the latest release from + [GitHub Releases](https://github.com/J3vb/OwnCord/releases) +2. Run `chatserver.exe` — generates `config.yaml` on first run 3. Open `https://localhost:8443/admin` to access the admin panel -4. Generate an invite code, share it with friends -5. Friends download the client installer and connect using - your server address - -## Building from Source - -### Server - -```bash -cd Server -go build -o chatserver.exe -ldflags "-s -w -X main.version=1.0.0" . -``` - -### Client (Tauri v2) - -```bash -cd Client/tauri-client -npm install -npm run tauri build -``` - -The installer is output to -`Client/tauri-client/src-tauri/target/release/bundle/nsis/`. +4. Generate an invite code and share it with friends +5. Friends download the client installer and connect + using your server address ## Architecture -OwnCord consists of a Go server and a Tauri v2 desktop -client. The server handles all business logic, storage, -and real-time communication. Clients connect over WebSocket -for chat events, REST for history and uploads, and WebRTC -for voice/video. +Two components: a **Go server** and a **Tauri v2 client** +(Rust + TypeScript). ```text +---------------------+ +---------------------+ @@ -63,7 +95,7 @@ for voice/video. | | REST Client |--+------->| | REST API | | | +---------------+ | | +---------------+ | | +---------------+ | WebRTC | +---------------+ | -| | Voice/Video |--+------->| | TURN/STUN | | +| | Voice/Video |--+------->| | SFU (Pion) | | | +---------------+ | | +---------------+ | +---------------------+ | +---------------+ | | | SQLite DB | | @@ -71,16 +103,126 @@ for voice/video. +---------------------+ ``` +- **WebSocket** — chat messages, typing, presence, voice signaling +- **REST API** — message history, file uploads, channel management, auth +- **WebRTC** — voice and video via Pion SFU with built-in TURN/STUN + +## Project Structure + +```text +OwnCord/ +├── Server/ # Go server +│ ├── api/ # REST handlers + middleware +│ ├── ws/ # WebSocket hub + SFU +│ ├── db/ # SQLite queries + migrations +│ ├── auth/ # Authentication + rate limiting +│ ├── config/ # YAML config loading +│ ├── updater/ # GitHub Releases update checker +│ ├── admin/ # Web admin panel (static SPA) +│ └── storage/ # File upload storage +├── Client/ +│ └── tauri-client/ # Tauri v2 desktop client +│ ├── src-tauri/ # Rust backend (plugins, commands) +│ ├── src/ # TypeScript frontend +│ │ ├── lib/ # Core services (API, WS, WebRTC, updater) +│ │ ├── stores/ # Reactive state (auth, channels, messages, voice) +│ │ ├── components/ # UI components (34 modules) +│ │ ├── pages/ # Page layouts +│ │ └── styles/ # CSS +│ └── tests/ # Unit, integration, and E2E tests +└── docs/ # Project documentation (Obsidian vault) +``` + +## Building from Source + +### Prerequisites + +- Go 1.25+ +- Node.js 20+ +- Rust (stable) +- Windows 10/11 + +### Server + +```bash +cd Server +go build -o chatserver.exe -ldflags "-s -w -X main.version=1.0.0" . +``` + +### Client + +```bash +cd Client/tauri-client +npm install +npm run tauri build +``` + +The installer is output to +`Client/tauri-client/src-tauri/target/release/bundle/nsis/`. + +### Running Tests + +```bash +# Server +cd Server && go test ./... + +# Client +cd Client/tauri-client +npm test # unit tests (vitest) +npm run test:e2e # Playwright E2E tests +npm run test:coverage # coverage report +``` + +## Configuration + +The server generates a `config.yaml` on first run. Key settings: + +| Setting | Default | Description | +| ------- | ------- | ----------- | +| `server.port` | `8443` | HTTPS port | +| `server.name` | `OwnCord Server` | Display name | +| `tls.mode` | `selfsigned` | TLS mode (see docs) | +| `upload.max_size_mb` | `10` | Max upload size | +| `voice.quality` | `medium` | `low`, `medium`, `high` | +| `voice.turn_enabled` | `true` | Built-in TURN server | +| `github.token` | — | Token for update checks | + +## Auto-Updates + +The client checks for updates after connecting to the server. +Updates are Ed25519-signed and verified before install. + +To enable signed releases in CI, add these GitHub repository secrets: + +- `TAURI_SIGNING_PRIVATE_KEY` — Ed25519 private key + (via `npx tauri signer generate`) +- `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` — key password + ## Documentation -- [Quick Start Guide](docs/quick-start.md) -- [Port Forwarding Guide](docs/port-forwarding.md) -- [Tailscale Guide](docs/tailscale.md) -- [Client Architecture](CLIENT-ARCHITECTURE.md) -- [Migration Plan](MIGRATION-PLAN.md) -- [Testing Strategy](TESTING-STRATEGY.md) -- [Contributing](CONTRIBUTING.md) -- [Security](SECURITY.md) +Detailed docs live in the `docs/brain/` Obsidian vault: + +- [Quick Start Guide](docs/brain/08-Guides/quick-start.md) +- [Port Forwarding Guide](docs/brain/08-Guides/port-forwarding.md) +- [Tailscale Guide](docs/brain/08-Guides/tailscale.md) +- [Client Architecture](docs/brain/06-Specs/CLIENT-ARCHITECTURE.md) +- [Server Spec](docs/brain/06-Specs/CHATSERVER.md) +- [WebSocket Protocol](docs/brain/06-Specs/PROTOCOL.md) +- [REST API](docs/brain/06-Specs/API.md) +- [Database Schema](docs/brain/06-Specs/SCHEMA.md) +- [Testing Strategy](docs/brain/06-Specs/TESTING-STRATEGY.md) +- [Contributing](docs/brain/08-Guides/CONTRIBUTING.md) +- [Security](docs/brain/08-Guides/SECURITY.md) + +## Tech Stack + +| Component | Technology | +| --------- | --------- | +| Server | Go, chi router, Pion WebRTC | +| Database | SQLite (pure Go, embedded) | +| Client | Tauri v2 (Rust + TypeScript) | +| Voice/Video | WebRTC with SFU, built-in TURN/STUN | +| Build | NSIS installer, GitHub Actions CI | ## License