02ab3e45cd
Adds an executable skill that takes a GPU index and (re)deploys the
migrated apps/dreamverse backend + Next.js frontend cleanly. Also extends
the contributing doc with the additional Phase 0 prereqs Oracle flagged
during the post-migration verification pass.
* .agents/skills/dreamverse-deploy/SKILL.md (new): documents the skill's
contract — args, env overrides, prereqs, what it does and does NOT do,
teardown, and the e2e wrapper command for follow-up Playwright runs.
* .agents/skills/dreamverse-deploy/scripts/dreamverse-deploy.sh (new):
- Validates prereqs upfront (apps/dreamverse, wrapper script, .venv,
flashinfer-python, pnpm, gcc-13/g++-13).
- Kills processes by port pattern AND by GPU UUID via
`nvidia-smi --query-compute-apps`. The earlier naive port-only kill
missed orphan multiproc_executor worker subprocesses, which then OOM'd
the next deploy on the same GPU.
- Sources ~/.env for provider API keys, exports the full env recipe
(CUDA_VISIBLE_DEVICES, FASTVIDEO_*, gcc-13 + NVCC_PREPEND_FLAGS for
flashinfer JIT against gcc-15 conda toolchain on B200/sm_100a).
- Launches backend via apps/dreamverse/scripts/dreamverse-server in a
detached setsid session, polls /readyz up to 5 min.
- Launches frontend via pnpm run dev:devtools (or `next dev --port` for
non-default port) with NEXT_PUBLIC_INCLUDE_DEVTOOLS=1, polls / up to
60s.
- Prints URLs, PIDs, log paths, stop command, e2e command at end.
- Supports `--stop` (port-pattern teardown) and `--stop <GPU>` (also
nukes any process holding that GPU).
* docs/contributing/dreamverse-development.md: Phase 0 prereqs section
extended per Oracle review (D-19 follow-up):
- Adds cerebras-cloud-sdk + openai to the install command (required by
the migrated prompt enhancer; without them, server fails to import
provider clients).
- Documents the gcc-13 / NVCC_PREPEND_FLAGS workaround for B200 hosts
with gcc-15 conda toolchain. Without these, flashinfer JIT compilation
fails at first NVFP4 use.
- Cross-links to the new dreamverse-deploy skill as the recommended
local-deploy path.
Verified: skill ran end-to-end on this dev node (GPU 4, ports 8009/5274),
backend boots /readyz=200 with /proc/$PID/cwd = apps/dreamverse/server,
frontend serves 200 on :5274, all 8 Playwright e2e specs pass against the
migrated stack in 5.1s.
Co-authored-by: Junda (David) Su <90978028+Davids048@users.noreply.github.com>
Co-authored-by: Matthew Noto <99706358+RandNMR73@users.noreply.github.com>
Co-authored-by: XOR-op <17672363+XOR-op@users.noreply.github.com>
Co-authored-by: Zhang Peiyuan <42993249+jzhang38@users.noreply.github.com>
100 lines
3.3 KiB
Markdown
100 lines
3.3 KiB
Markdown
# Dreamverse Development
|
|
|
|
Dreamverse lives under `apps/dreamverse/` as a product app inside the
|
|
FastVideo monorepo. Backend code uses the local FastVideo workspace package;
|
|
frontend tooling remains standalone under `apps/dreamverse/web/`.
|
|
|
|
## Backend tests
|
|
|
|
Run CPU-safe backend tests from the FastVideo repository root:
|
|
|
|
```bash
|
|
uv run --locked --package dreamverse --extra test pytest apps/dreamverse/server/tests/ -m 'not gpu' -q
|
|
```
|
|
|
|
## Backend launch
|
|
|
|
Launch the migrated backend through the repo-local wrappers:
|
|
|
|
```bash
|
|
apps/dreamverse/scripts/dreamverse-server --port 8009
|
|
apps/dreamverse/scripts/dreamverse-mock-server --port 8009
|
|
```
|
|
|
|
Do not rely on a bare `dreamverse-server` found on `PATH` during the migration.
|
|
With `[tool.uv] package = false`, uv does not register this workspace member's
|
|
console scripts, so a PATH binary can still point at an old Dreamverse editable
|
|
install outside this monorepo.
|
|
|
|
## Frontend build and tests
|
|
|
|
Run frontend commands from the standalone web app:
|
|
|
|
```bash
|
|
cd apps/dreamverse/web
|
|
pnpm install --frozen-lockfile
|
|
pnpm run build
|
|
pnpm run test
|
|
```
|
|
|
|
Playwright is intentionally run against a live backend as part of the GPU4
|
|
manual verification flow, not in the Phase 3 migration gate.
|
|
|
|
## Local GPU4 verification hook
|
|
|
|
Use physical GPU 4 for migration smoke tests. `CUDA_VISIBLE_DEVICES=4` makes
|
|
that GPU appear as logical GPU 0 inside the process, preserving the previous
|
|
Dreamverse deployment behavior.
|
|
|
|
```bash
|
|
CUDA_VISIBLE_DEVICES=4 apps/dreamverse/scripts/dreamverse-server \
|
|
--host 0.0.0.0 --port 8009
|
|
```
|
|
|
|
In another shell, verify the service:
|
|
|
|
```bash
|
|
curl -s http://localhost:8009/healthz
|
|
```
|
|
|
|
Phase 4 adds the public `/healthz`, `/readyz`, `/status`,
|
|
`/prompt-system-config`, and `/curated-presets` route coverage needed for the
|
|
full Playwright suite.
|
|
|
|
## Phase 0 production-equivalent prerequisites
|
|
|
|
For the production-equivalent NVFP4 path, install these dependencies
|
|
in the FastVideo `.venv` before GPU smoke tests:
|
|
|
|
```bash
|
|
uv pip install --python .venv/bin/python \
|
|
flashinfer-python flash-attn cerebras-cloud-sdk openai \
|
|
--no-build-isolation
|
|
```
|
|
|
|
| Package | Why |
|
|
|---|---|
|
|
| `flashinfer-python` | Required for NVFP4 quantization. Without it, model load fails with `ImportError: NVFP4 quantization requires flashinfer`. |
|
|
| `flash-attn` | Optional but recommended; without it attention falls back to Torch SDPA (functional but slower). |
|
|
| `cerebras-cloud-sdk` | Required by the migrated prompt enhancer for the default `cerebras` provider. |
|
|
| `openai` | Required by the prompt enhancer's OpenAI-compatible providers + downstream rewrites. |
|
|
|
|
### B200 / sm_100a + gcc-15 conda toolchain (flashinfer JIT workaround)
|
|
|
|
On hosts where the conda toolchain ships gcc-15 (which nvcc rejects with
|
|
`#error -- unsupported GNU version! gcc versions later than 14 are not
|
|
supported!`), set these env vars before launching anything that triggers
|
|
flashinfer's JIT kernel build:
|
|
|
|
```bash
|
|
export CC=/usr/bin/gcc-13
|
|
export CXX=/usr/bin/g++-13
|
|
export CUDAHOSTCXX=/usr/bin/g++-13
|
|
export NVCC_PREPEND_FLAGS="-ccbin /usr/bin/gcc-13 -allow-unsupported-compiler"
|
|
```
|
|
|
|
The `apps/dreamverse/scripts/dreamverse-server` wrapper does NOT set these —
|
|
they need to come from the launching shell. The `dreamverse-deploy` skill
|
|
([`.agents/skills/dreamverse-deploy/`](../../.agents/skills/dreamverse-deploy/SKILL.md))
|
|
sets them for you and is the recommended local-deploy path.
|