mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-07-26 12:08:15 +00:00

Files

T

MacBook 5157428e74 docs: comprehensive repository polish + step-by-step user guide

Documentation Rewrites:
- AI_INIT.md: fix duplicate section numbers, add file responsibility map,
  fix stale manual mirror instruction, add room ID constraint
- PRIVACY.md: add TL;DR statement, data retention table, explicit
  <all_urls> justification, self-hosted instance disclaimer
- CONTRIBUTING.md: add local testing guide, version warning, room ID
  constraint, bug report requirements
- shared/README.md: complete event table (all 15 events), fix stale
  manifest.json reference
- docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list,
  drop stale RC5 reference
- server/README.md: sync env defaults with .env.example (1000/50)

New Documentation:
- docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation,
  invitation bridge flow, synchronized playback, force sync protocol,
  heartbeat system, and episode auto-sync. Includes exact data payloads.

Infrastructure Cleanup:
- docker-compose.yml: remove deprecated version key
- .dockerignore: remove dead .bat/.sh patterns
- README.md: add self-hosting extension config tip, link HOW_IT_WORKS

2026-05-04 05:41:43 +02:00

1.2 KiB

Raw Blame History

KoalaSync Relay Server

A high-performance Node.js relay server for synchronized video playback.

Key Features

Zero-Persistence: No database. All state is held in RAM.
Privacy First: No tracking, no logging of user data.
WebSocket Only: High performance with minimal overhead.

Setup

Environment

Copy .env.example to .env and configure your settings.

PORT=3000
MAX_ROOMS=1000
MAX_PEERS_PER_ROOM=50
MIN_VERSION=1.0.0

Docker (Recommended)

The server is available as a pre-built image on GHCR.

# Pull from GHCR
docker pull ghcr.io/shik3i/koalasync:latest

# Or build from the repository root
docker build -t koala-sync-server -f server/Dockerfile .

See docker-compose.example.yml in the root directory for a ready-to-use configuration.

Manual Setup

cd server
npm install
npm start

Security

Rate Limiting: IP-based connection limits and socket-based event limits.
Token Handshake: Requires a valid token defined in the root shared/constants.js.
Single Source of Truth: The server imports constants directly from the root shared/ directory.
In-Memory: Rooms are automatically pruned after 2 hours of inactivity.

1.2 KiB Raw Blame History