WatchLink is a self-hosted shared-watch web app with persistent user rooms, local accounts, friends, role-based administration, and realtime playback state.

Features

First-run setup creates the first admin user.
Username/password accounts with bcrypt password hashing.
Every user gets a stable personal room like /rooms/@username.
Friend requests and room access are modeled for friends-only, public, role-restricted, and explicit access.
Admin surface for rooms, users, roles, and permissions.
Shared playback state via Socket.IO.
Media URL normalization for YouTube, Twitch, and direct video URLs.
Uptime Kuma/Dockge-inspired app shell with system light/dark theme.
Docker Compose stack for app and Postgres.

Development

npm install
cp .env.example .env
npm run db:push
npm run dev

Open http://localhost:3000/setup on a clean database to create the first admin.

Useful commands:

npm run typecheck
npm run test
npm run build
npm run audit

Docker

docker compose up --build

The Compose stack exposes the web app on http://localhost:3000 and uses a Postgres volume named watchlink_postgres-data.

Build and publish the Gitea image:

docker build -t git.wilkensxl.de/MrSphay/watchlink:latest .
docker login git.wilkensxl.de
docker push git.wilkensxl.de/MrSphay/watchlink:latest

Gitea

Target repository:

git@git.wilkensxl.de:MrSphay/WatchLink.git

Target container image:

git.wilkensxl.de/MrSphay/watchlink:latest

CI expects REGISTRY_TOKEN to be configured as a repository or organization secret when image publishing should run.

Project Info

Stack: Next.js, React, TypeScript, Prisma, Postgres, Socket.IO, Docker
Repository baseline: codex-agent-repository-kit
License: not declared yet