WatchLink

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.
Site-wide instance settings for registration mode, default room visibility, media providers, and avatar upload limits.
Profile settings with display name and profile picture upload.
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:migrate
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

Create a production .env file before starting Compose:

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:

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:

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:

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.

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

4.9 KiB Raw Blame History