watch-party/README.md

# Watch Party (Frontend + Backend)

Watch Party is a small full-stack app for synchronized viewing with a live timer and episode control.

## Features
- Live timer with server-synced clock and schedule-driven start/end.
- Episode selector (set current episode + optional custom start time).
- Time-skew banner (warns when client clock is off).
- Debug-only logging overlay and error toasts for API failures (enable with `FRONTEND_MODE=debug` / `VITE_APP_MODE=debug`).

## Prerequisites
- Docker + Docker Compose plugin.
- Node.js 20+ (for local frontend dev/test).
- Go 1.22+ (for local backend dev/test).
- A `.env` file at repo root (see template below).

## Deploy (compose)
```bash
docker compose build
docker compose up -d
```
Open: `http://<mac-mini-LAN-IP>:3000/watch-party/`

Health checks:
- Web (nginx): `curl http://<mac-mini-LAN-IP>:3000/`
- API via web proxy: `curl http://<mac-mini-LAN-IP>:3000/api/healthz`
- API direct (inside network): `curl http://api:8082/healthz`

Logs:
```bash
docker compose logs -f migrate
docker compose logs -f api
docker compose logs -f web
docker compose logs -f db
```

Architecture:
```
router → Debian nginx (TLS) → Mac mini :3000 → [web nginx ↔ api ↔ db]
```

---

## Repository Layout

```
.
├── docker-compose.yml      # single compose for web + api + db + migrate
├── .env                    # stack configuration (see template below)
├── backend/                # Go API + migrations
│   ├── cmd/
│   │   ├── migrate/        # one-off migration binary
│   │   └── server/         # API server (Gin)
│   ├── db/migration/       # SQL migrations (0001_init.sql, etc.)
│   ├── Dockerfile          # builds server + migrate
│   └── go.mod / go.sum
└── frontend/               # Vite + React + TS
    ├── Dockerfile          # Vite build → Nginx runtime (envsubst for proxy)
    ├── ops/                # container runtime bits
    │   ├── entrypoint.sh
    │   ├── nginx.conf      # (optional/manual)
    │   └── nginx.conf.template  # uses BACKEND_ORIGIN
    ├── src/, public/, vite.config.ts, package*.json, tsconfig*.json
```

---

## Services (Compose)

- **web**: Nginx serving the built SPA, and proxying `/api/*` to `api:8082` (Docker DNS)
- **api**: Go server (Gin), listens on `:8082`, health at `/healthz`
- **migrate**: one-off job that runs the `migrate` binary, applies SQL from `backend/db/migration`
- **db**: PostgreSQL 16 (internal only)

Only **web** is published to your LAN (port `3000` by default). `api` and `db` are internal to the compose network.

---

## .env (template)

```dotenv
##################
## Frontend env ##
##################
WEB_PORT=3000
PUBLIC_BASE_PATH=/watch-party/
BACKEND_ORIGIN=http://api:8082

#################
## Backend env ##
#################
# Postgres (container)
POSTGRES_DB=watchparty
POSTGRES_USER=admin
POSTGRES_PASSWORD=change-me
TZ=Asia/Tokyo
COMPOSE_PLATFORM=linux/arm64/v8

# Backend server
ADDR=:8082
GIN_MODE=release
PGHOST=db
POSTGRES_PORT=5432
PGSSLMODE=disable
```

> **Why mixed names?** The current Go code builds its DSN from `PGHOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, and `PGSSLMODE`.

---

## Debian Nginx (public reverse proxy)

Terminate TLS on Debian and forward to the Mac mini:

```nginx
# Serve the SPA under /watch-party/
location /watch-party/ {
  proxy_pass http://<mac-mini-LAN-IP>:3000/watch-party/;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $remote_addr;
}

# Proxy API via the web container (keeps same-origin from browser POV)
location /api/ {
  proxy_pass http://<mac-mini-LAN-IP>:3000/api/;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $remote_addr;
}
```

Security headers & HSTS on Debian are recommended.

---

## Local Development (hot reload)
See per-service READMEs:
- Frontend: `frontend/README.md`
- Backend: `backend/README.md`

---

## Notes & Conventions

- **Only `web` is exposed** to the LAN. `api` and `db` are `expose`d internally.
- The frontend **does not** use `host.docker.internal`; it proxies to `api:8082` by Docker DNS.
- Backend healthcheck probes `http://localhost:8082/healthz` and the server binds `ADDR=:8082`.
- Migrations live in `backend/db/migration/` and are applied by the **migrate** container at startup.
- Vite base path is controlled by `PUBLIC_BASE_PATH` (e.g., `/watch-party/`).

---

## Quick Test Endpoints

```bash
# Latest health:
curl http://<mac-mini-LAN-IP>:3000/api/healthz

# Current show (if table seeded and current_ep=true):
curl http://<mac-mini-LAN-IP>:3000/api/current
```

---

## Troubleshooting

- **Migrate “hangs” / API starts instead**  
  Ensure the backend image uses `CMD` (not `ENTRYPOINT`) and compose sets:
  ```yaml
  migrate:
    command: ["/app/migrate"]
  api:
    command: ["/app/server"]
  ```
- **404 for deep links** under `/watch-party/`  
  Confirm SPA fallback is active in `frontend/ops/nginx.conf.template` and Vite `base` matches `PUBLIC_BASE_PATH`.
- **DB not reachable**  
  Check `.env` values match the mixed DSN env names. `PGHOST=db`, `POSTGRES_PORT=5432`, etc.
- **CORS issues**  
  There shouldn’t be any—browser hits `web`, which proxies to `api`, so it’s same-origin.

---

## License

MIT