WatchLink/blueprint.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.

{{ template:section-line }}

Features

• First-run admin setup
• Username/password accounts
• Persistent user rooms
• Friend graph and access modes
• Shared playback state for YouTube, Twitch, and direct video URLs
• Uptime Kuma/Dockge-inspired app shell
• Dockerized Next.js and Postgres stack

{{ template:section-line }}

Development

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

{{ template:section-line }}

Docker

Production .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

Minimal Compose using the published image:

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"
    command: sh -c "./node_modules/.bin/prisma migrate deploy && node server.js"

volumes:
  postgres-data:

docker compose up --build

Target image: git.wilkensxl.de/mrsphay/watchlink:latest