WatchLink/README.md

# WatchLink

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

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## 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 for friends-only, public, role-restricted, and explicit access.
- Admin surface for rooms, users, roles, invites, security settings, and audit events.
- Site-wide instance settings for registration mode, default room visibility, media providers, and avatar upload limits.
- Profile settings with display name, profile picture upload, password change, and logout.
- Shared playback state via Socket.IO with Postgres-persisted room state.
- Persistent room chat and queue updates through the realtime room channel.
- 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.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Development

```bash
npm install
cp .env.example .env
npm run db:migrate
npm run dev
```

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

Useful commands:

```bash
npm run typecheck
npm run test
npm run build
npm run audit
```

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Docker

Create a production `.env` file before starting Compose:

```env
POSTGRES_DB=watchlink
POSTGRES_USER=watchlink
POSTGRES_PASSWORD=change-this-database-password
NEXTAUTH_URL=https://watchlink.example.com
NEXTAUTH_SECRET=change-this-with-openssl-rand-base64-32
HOST_PORT=6852
```

For local testing, use:

```env
POSTGRES_DB=watchlink
POSTGRES_USER=watchlink
POSTGRES_PASSWORD=watchlink
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change-me-with-openssl-rand-base64-32
HOST_PORT=3000
```

Minimal `docker-compose.yml` using the published Gitea image:

```yaml
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-watchlink}
      POSTGRES_USER: ${POSTGRES_USER:-watchlink}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-watchlink}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-watchlink} -d ${POSTGRES_DB:-watchlink}"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    image: git.wilkensxl.de/mrsphay/watchlink:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER:-watchlink}:${POSTGRES_PASSWORD:-watchlink}@postgres:5432/${POSTGRES_DB:-watchlink}?schema=public
      NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET:-change-me-with-openssl-rand-base64-32}
      PORT: 3000
    ports:
      - "${HOST_PORT:-3000}:3000"
    volumes:
      - avatar-uploads:/app/public/uploads
    command: sh -c "./node_modules/.bin/prisma migrate deploy && node server.js"

volumes:
  postgres-data:
  avatar-uploads:
```

Start the stack:

```bash
docker compose up --build
```

The Compose stack exposes the web app on `http://localhost:${HOST_PORT:-3000}` and uses named volumes for Postgres data and uploaded avatars. Keep the container `PORT` at `3000`; change `HOST_PORT` when another container already uses port 3000 on the host.

On first start, the web container runs `prisma migrate deploy` before starting Next.js. This creates the required tables in a clean Postgres volume.

### Provider notes

WatchLink uses the official YouTube IFrame API. If YouTube shows a sign-in or bot-check challenge inside the embed, WatchLink cannot bypass that provider-side restriction; the room shows a fallback action to open the video on YouTube. Twitch live streams support source and play/pause sync, while seek sync is available only for Twitch VODs and direct video files.

### Uploads and invites

Uploaded avatars are stored below `/app/public/uploads` in the `avatar-uploads` Docker volume. Invite-only registration uses invite codes created in the Admin area; room-scoped invite codes also grant room membership when the account is created.

Build and publish the Gitea image:

```bash
docker build -t git.wilkensxl.de/mrsphay/watchlink:latest .
docker login git.wilkensxl.de
docker push git.wilkensxl.de/mrsphay/watchlink:latest
```

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Gitea

Target repository:

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

Target container image:

```text
git.wilkensxl.de/mrsphay/watchlink:latest
```

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

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Project Info

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