# Deployment

The maintained deployment target for this project is Windows first. Linux and macOS can still run services manually, but real end-to-end deployment testing should use the PowerShell flow below.

Runtime paths are resolved relative to the repository by default and can be overridden with environment variables.

- LS_DATABASE_URL: SQLAlchemy database URL.
- LS_REPLAY_MEDIA_DIR: server-local directory containing replay files. When started by start.ps1, the default is runtime\replay under the repository.
- LS_HLS_RUNTIME_DIR: backend and FFmpeg HLS output directory. When started by start.ps1, the default is runtime\hls under the repository.

## Windows deployment

Run these commands from PowerShell on the Windows node.

### 1. Install prerequisites

Required on PATH: Python 3.11+, FFmpeg, and MediaMTX. MediaMTX may instead be left in the repository's `mediamtx\` directory, which is where the backend looks second. Node.js is only needed to build the frontend for deployment.

### 2. Install application dependencies

```powershell
powershell -ExecutionPolicy Bypass -File .\start.ps1 -InstallDeps
```

### 3. Build the frontend

Once per deployment, and again whenever the frontend changes. The build output is
committed to the server by the build step and then served by the backend itself,
so **Node.js is a build-time dependency only** — production runs without it and
without a Vite dev server.

```powershell
cd frontend
npm install
npm run build
cd ..
```

Skipping this is not silent: the backend answers every page with HTTP 503 and
`s Frontend not built` until `frontend\dist` exists.

### 4. Start the stack

```powershell
powershell -ExecutionPolicy Bypass -File .\start.ps1
```

This starts one process on 0.0.0.0:8080 that owns everything:

- **The frontend** is served from `frontend\dist` on the same port. Unknown paths
  return the app shell so client-side routes survive a refresh.
- **MediaMTX** is started at boot if nothing is already answering its API on :9997, and restarted by the supervisor if it dies. Set `LS_MEDIA_ORIGIN_AUTOSTART=false` to manage it externally; the backend then only supervises transcoders.
- **Transcoders** are started for every live stream whose MediaMTX path is publishing, and restarted within ~10s of an ffmpeg process exiting. They encode on the GPU when one is available (see below).
- **HLS** is written under `runtime\hls` and served through `GET /hls/...`, which falls back to proxying MediaMTX's own HLS when the local files are absent.

Open http://127.0.0.1:8080/ for the site and /docs for the API. Publish RTMP to
rtmp://127.0.0.1:1935/live/<stream_key>.

### Hardware encoding

The transcoders detect the best encoder the host actually has, at startup, by
encoding a test frame with each candidate in turn:

1. `h264_nvenc` / `hevc_nvenc` (NVIDIA)
2. `h264_qsv` (Intel iGPU)
3. `h264_amf` (AMD)
4. `libx264` (CPU fallback)

Only encoders that really work are used — being compiled into ffmpeg is not
enough, since `h264_amf` fails without `amfrt64.dll` and `h264_qsv` fails without
an Intel iGPU. The choice is logged at startup as `[transcoder] hardware encoder:
…`, or `[transcoder] no working hardware encoder; falling back to libx264` with
the probed candidates listed. On the reference GTX 1060, one 1080p→720p
rendition costs ~62% of a core on NVENC versus ~109% on libx264 ultrafast.

### 5. Useful variants

```powershell
powershell -ExecutionPolicy Bypass -File .\start.ps1 -HostAddress 0.0.0.0 -BackendPort 8080
```

### 6. Smoke test commands

```powershell
curl.exe http://127.0.0.1:8080/api/health
curl.exe http://127.0.0.1:9997/v3/paths/list
ffmpeg -version
mediamtx --version
nvidia-smi
```

If browser or network tests run from another machine, open the Windows firewall for ports 8080, 1935, and 8888.

## Windows edge node launcher

Build and start an edge node from a Windows edge machine:

```powershell
powershell -ExecutionPolicy Bypass -File .\edge-agent\start-edge.ps1 -Build -OriginUrl http://<origin-host>:8080 -NodeId edge-win-01 -Region default -HlsPort 8889 -ApiPort 9997
```

For normal subsequent starts, omit `-Build`:

```powershell
powershell -ExecutionPolicy Bypass -File .\edge-agent\start-edge.ps1 -OriginUrl http://<origin-host>:8080 -NodeId edge-win-01 -Region default -HlsPort 8889 -ApiPort 9997
```

The launcher sets the StreamCore edge environment variables, starts the Windows edge-agent executable, stores runtime data under `ProgramData\StreamCore\edge\<node-id>` by default, and writes logs to that node data directory. The edge agent then manages its embedded MediaMTX edge process.

## Edge node scripts

```cmd
mediamtx\scripts\start_origin.bat
mediamtx\scripts\start_edge.bat 1 127.0.0.1
mediamtx\scripts\check_multicast.bat
```

## Replay file safety

Replay records store paths relative to LS_REPLAY_MEDIA_DIR. Absolute paths and parent-directory traversal are rejected.

## Linux and macOS

Linux and macOS are not the primary deployment path. For local development, run the backend with uvicorn from `backend`, run the frontend with `npm run dev` from `frontend`, and set `LS_HLS_RUNTIME_DIR` to a writable directory.