docs/WEB_DEV_GUIDE.md

# Web UI — developer guide

Set up, run, and deploy the Gemini Studio Web stack (FastAPI + React). Product scope: **[SPEC_WEB_UI.md](./SPEC_WEB_UI.md)**.

**Imports:** Code lives under `VideoGeneration-release/web/`. Use **`PYTHONPATH=.`** with cwd = **`VideoGeneration-release`** (parent of `web/`). Do not set `PYTHONPATH` to `web/` alone.

## 1. Prerequisites

- Python 3.10+
- Node.js 18+ and npm (frontend build)
- **ffmpeg** on `PATH` (strip audio from MP4s)

## 2. Python venv

From **`VideoGeneration-release`**:

```bash
cd /path/to/VideoGeneration-release
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r web/requirements.txt
```

## 3. Environment variables

Do not commit secrets; use a `.env` with your process manager if you like.

| Variable | Purpose |
|----------|---------|
| `GEMINI_API_KEY` | Server-side only. |
| `WEB_UI_PASSWORD` | Login password. |
| `SESSION_SECRET` | Session signing, e.g. `openssl rand -hex 32`. |
| `GENERATION_OPTIONS_PATH` | Optional. Overrides default `web/config/generation_options.json`. |

```bash
export GEMINI_API_KEY="your_key"
export WEB_UI_PASSWORD="password"
export SESSION_SECRET="$(openssl rand -hex 32)"
```

## 4. `generation_options.json`

Edit **`web/config/generation_options.json`** (or the file from `GENERATION_OPTIONS_PATH`). The UI loads **`GET /api/config/generation-options`** after login. JSON-only changes need no frontend rebuild; React/TS/CSS changes do.

- **`image`**: `models` (`value` + `label`), `aspect_ratios`, `resolutions`, `thinking_levels`.
- **`video`** / **`video_frames`**: `models`, `aspect_ratios`, `resolutions`, `durations_seconds`. On **`video`**, **`supports_reference_images`** (e.g. Veo Lite = `false`). With reference images, duration is forced to **8s**. **首尾帧** route always **8s** (no 4/6s like prompt-only 720p).

## 5. Build frontend

```bash
cd web/frontend
npm install
npm run build
```

Output: **`web/backend/static/`**. Missing build → root URL returns 503.

## 6. Run server

```bash
cd /path/to/VideoGeneration-release
PYTHONPATH=. uvicorn web.backend.main:app --host 127.0.0.1 --port 8000
```

LAN: `--host 0.0.0.0`. Dev: add `--reload`.

## 7. Dev mode (hot reload)

**A** — API, cwd **`VideoGeneration-release`**:

```bash
PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000
```

**B** — Vite (`web/frontend`): `npm run dev` (proxies `/api` to 8000). Open the printed URL (e.g. `http://127.0.0.1:5173`).

## 8. Stable URL

The app does not provide a hostname. Use DNS to a domain you control, static/elastic IP, reverse proxy (nginx/Caddy), or a tunnel (Cloudflare Tunnel, Tailscale Funnel, etc.). **One DNS name → current server** when you move machines.

## 9. Checklist

- [ ] `ffmpeg -version`
- [ ] `pip install -r web/requirements.txt`
- [ ] `npm run build` in `web/frontend` at least once
- [ ] `GEMINI_API_KEY`, `WEB_UI_PASSWORD`, `SESSION_SECRET` set
- [ ] Uvicorn from **`VideoGeneration-release`** with `PYTHONPATH=.`

## 10. Hugging Face Spaces (Docker)

Use **Docker** (`sdk: docker`), not Streamlit/Gradio. **`Dockerfile`** at repo root next to `web/` and `assets/`.

### 10.1 Create Space

[Hugging Face](https://huggingface.co/) → New Space → **SDK: Docker**. Space id: **`YOUR_USERNAME/YOUR_SPACE_NAME`**.

### 10.2 Root `README.md`

YAML frontmatter must validate. This repo’s README is preconfigured.

- **`sdk: docker`**
- **`colorFrom`** / **`colorTo`**: each must be one of **`red`**, **`yellow`**, **`green`**, **`blue`**, **`indigo`**, **`purple`**, **`pink`**, **`gray`** (other names → upload error).

### 10.3 Upload

**Cwd:** **`VideoGeneration-release`** (contains `Dockerfile`, `web/`, `assets/`).

**CLI** ([write token](https://huggingface.co/settings/tokens)):

```bash
pip install -U huggingface_hub
huggingface-cli login
cd /path/to/VideoGeneration-release
hf upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type space
```

Example:

```bash
hf upload LehongWu/VideoGeneration-release . . --repo-type space
```

Then check **Space → Logs** for the Docker build.

**Git:**

```bash
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git push -u hf main
```

Or connect GitHub in Space settings and push there.

### 10.4 Secrets

**Settings → Variables and secrets** — names must match exactly (case-sensitive). Same as [§3](#3-environment-variables).

| Name | Purpose |
|------|---------|
| `GEMINI_API_KEY` | Gemini key; never commit. |
| `WEB_UI_PASSWORD` | Login password. |
| `SESSION_SECRET` | e.g. `openssl rand -hex 32`. |

Optional: `GENERATION_OPTIONS_PATH` (custom JSON path inside the container).

Saving restarts the Space. Never put secrets in Git or `README.md`.

### 10.5 Runtime

- Listens on **`PORT`** or **`7860`** (`Dockerfile`: `uvicorn ... --port ${PORT:-7860}`).
- **`--forwarded-allow-ips='*'`** — required behind HF’s reverse proxy so `X-Forwarded-Proto: https` is trusted. Without it, Uvicorn often sees `http`, session cookies misbehave, and the UI **keeps asking you to log in**.
- **ffmpeg** in image.
- First build / cold start can take minutes.

### 10.6 Local Docker

```bash
cd /path/to/VideoGeneration-release
docker build -t gemini-studio-web .
docker run --rm -p 7860:7860 \
  -e GEMINI_API_KEY="your_key" \
  -e WEB_UI_PASSWORD="your_password" \
  -e SESSION_SECRET="$(openssl rand -hex 32)" \
  gemini-studio-web
```

Open `http://127.0.0.1:7860`.