Install

There are three ways to run Channel Vault NAS. Pick one:

• Docker (recommended)

  ---

  Pull the published images and run the Compose stack — the fastest path, and the one used for NAS deployments.

  Docker install

• NAS (Synology / QNAP)

  ---

  Container Manager / Container Station, separate host folders, reverse proxy, and a public compatibility-report thread.

  NAS install

• Local development

  ---

  Run the FastAPI backend and the Vite dev server directly for hacking on the code.

  Local dev

Prerequisites

Docker / NASLocal development

• Docker with the Compose plugin (docker compose)
• ~300 MB for the images, plus disk space for your archive

• Python 3.11+
• Node.js 20+ (CI verifies with Node.js 24)
• yt-dlp
• ffmpeg / ffprobe

The three run modes

Mode	Best for	Guide
Pull a published image	A fast, reproducible install	Docker → published images
Compose build from source	Evaluating the current main / a branch	Docker → build from source
Local development	Editing backend/frontend code	Local development

Both Docker paths store archive data in bind-mounted host folders, so your media and metadata live on disk — not inside a container layer.

NAS operators: separate your folders first

Before the first start, put SQLite metadata, downloaded media, and runtime overrides on three separate host folders so each can be backed up independently. See NAS install.

Check compatibility and real NAS reports for verified architectures and community-tested hardware.

After install

1. Open the web console at http://127.0.0.1:5173/.
2. Follow Your first channel backup to archive your first channel.
3. Real downloads stay disabled until you click Start automatic backup (which enables the worker for you) or run the advanced manual test.

You only see {\"detail\":\"Not Found\"}?

You opened the raw API port instead of the web console. Open the web port (CVN_WEB_PORT, default 5173). The API port only serves paths like /api/health. Full explanation in NAS troubleshooting.