Vigil

Quickstart

How to run Vigil.

Quickstart

This quickstart runs Vigil, creates the first administrator, and verifies the setup. It gives the commands for development and for production.

Prerequisites

To run Vigil in development and build the production binary, you need:

  • Bash.
  • Bun (version 1.3.14).
  • Go (version 1.26 or later).
  • Make.
  • MediaMTX.
  • FFmpeg.

The repository uses Bun for JavaScript packages and Bash plus Make for the production build command. The backend uses Go. MediaMTX is the media server. FFmpeg provides snapshots and stream probing.

Install The Dependencies

Install the JavaScript dependencies with Bun:

bun install

MediaMTX is available as a local binary in .bin/mediamtx. The launcher in tools/mediamtx/run.sh uses this binary first. It falls back to mediamtx from the PATH.

1. Run In Development

The root package has a dev script that runs all development tasks:

bun run dev

You can run one part at a time:

bun run dev:server      # Go API on :8080
bun run dev:mediamtx    # MediaMTX
bun run dev:dashboard   # Dashboard on :5173
bun run dev:landing     # Landing page
bun run dev:mobile      # Mobile app

The dashboard dev server proxies the API and the MediaMTX streams. The proxy is configured in apps/dashboard/vite.config.ts.

2. Bootstrap The First Admin

When you run the server for the first time, there are no users. The system asks you to create the first administrator.

Open the dashboard in a browser. You will see the setup form. Create an administrator account. Then log in.

See setup-and-authentication for the details of first-start setup.

3. Verify The Server

To verify that the server runs, open this URL in a browser:

http://localhost:8080/api/v1/health

The response is a JSON object with a status field, for example {"status":"ok"}.

To verify that MediaMTX runs, open its API:

http://127.0.0.1:9997/v3/paths/list

4. Build The Production Binary

Build the dashboard and the Go server together:

bun run build:bin
./server/bin/nvrd

The build command copies the dashboard into the Go embed directory, so the single binary serves the API and dashboard on :8080.

Runtime state defaults to ./data and ./recordings relative to the directory where nvrd is launched. Moving the binary does not move its state. Set NVR_DATA_DIR and NVR_RECORDINGS_DIR to absolute paths when the server can be started from different working directories.

Headless (hosted dashboard) binary

If you run the dashboard as a separate hosted service and point the recorder at it, build the slim/headless binary. It omits the embedded dashboard and serves a connection page that deep-links to the hosted dashboard:

cd server && make build-slim        # produces bin/nvrd-slim

The hosted dashboard, the recorder's public HTTPS URL, and the allowed CORS origins are configured at first run with nvrd setup. See setup-and-authentication.

5. Bootstrap With nvrd setup (CLI)

nvrd setup creates the first administrator and persists the public and hosted dashboard URLs. The password is never shown on the command line. Interactive:

./server/bin/nvrd setup \
  --public-url https://recorder.example.com \
  --hosted-url https://nvr.example.com/dashboard

It prompts for the admin username and password (hidden input). Non-interactive (first-start automation):

cd server && go run ./cmd/nvrd setup \
  --username admin \
  --password-stdin \
  --public-url https://recorder.example.com \
  --hosted-url https://nvr.example.com/dashboard \
  --non-interactive <<< 'a-strong-password'

--password-stdin reads the password from standard input instead of a terminal prompt, so it never appears in argv. Once an admin exists, nvrd setup rejects credential-bearing reruns and only allows URL-only updates. See setup-and-authentication for all flags, the env first-start bootstrap, and the validation rules.

6. Run With Docker

To run Vigil with Docker:

cd deploy && docker compose up --build

For the headless/hosted-dashboard image (no embedded UI):

cd deploy && docker build --target runtime-slim -t nvr-slim ..

See operations for the details of the Docker setup.

Code Generation

The API contract generates the Go server stubs and the TypeScript client. To regenerate the TypeScript client:

bun run gen:api

To regenerate the Go server:

bun run gen:server

See development for the details of code generation.

Verify The Setup

Run these checks:

bun run lint          # Biome format and lint
bun run check-types   # TypeScript type checks

The Go backend has its own build and test commands inside server/. See development for the details.

Next Steps