Files
live/DEPLOYMENT.md
T

233 lines
10 KiB
Markdown

# 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 service: autostart behind nginx
`start.ps1` above is the manual/dev path: one foreground process on :8080 that
serves the frontend itself. On the production box the stack instead runs as a
background service behind nginx, and `scripts\streamcore-service.ps1` owns it.
```powershell
# one-off, elevated: register the boot task
powershell -ExecutionPolicy Bypass -File .\scripts\streamcore-service.ps1 -Action Install
# day to day
powershell -ExecutionPolicy Bypass -File .\scripts\streamcore-service.ps1 -Action Status
powershell -ExecutionPolicy Bypass -File .\scripts\streamcore-service.ps1 -Action Restart
powershell -ExecutionPolicy Bypass -File .\scripts\streamcore-service.ps1 -Action Stop
powershell -ExecutionPolicy Bypass -File .\scripts\streamcore-service.ps1 -Action Doctor
```
- The scheduled task `StreamCore-AutoStart` fires at startup as **SYSTEM**, with a
20-second delay, no execution time limit, and restart-on-failure. It runs in
session 0, so no console window ever appears.
- nginx is `D:\nginx-1.31.6`, started with `-p D:\nginx-1.31.6` so the relative
paths in `conf\nginx.conf` resolve inside that directory. It serves
`frontend\dist` and the HLS segments from disk and proxies `/api/`, `/docs`,
`/openapi.json` and the HLS fallback to `127.0.0.1:8080`.
- The backend is plain `uvicorn main:app --port 8080` against the machine-wide
Python install, not a venv. If it dies the launcher restarts it after 10s, and
nginx is re-checked on every 15s health tick.
- MediaMTX is still owned by the backend, which starts it if nothing answers
:9997 (see `LS_MEDIA_ORIGIN_AUTOSTART` above).
Two things about running as SYSTEM are worth knowing, because both fail *only*
in service mode:
- **ffmpeg.** winget installs it per-user, so SYSTEM never sees it on PATH. The
launcher prepends `%LOCALAPPDATA%\Microsoft\WinGet\Links` explicitly. Run
`-Action Doctor` and check the `executables` block after a reboot to confirm.
- **`nginx -s reload` / `-s stop`.** nginx signals its master through the global
event `Global\ngx_stop_<pid>`, which an administrator shell cannot open
(`OpenEvent ... Access is denied`). Use `-Action Restart` after editing
`nginx.conf`; it replaces the worker tree directly.
Logs land in `runtime\logs`: `backend.err.log` (uvicorn banner) and
`backend.out.log` (request log), `service.log` (what the launcher did),
`nginx-launch.*.log`, plus nginx's own logs in `D:\nginx-1.31.6\logs`.
## 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 (systemd, production)
Reference host: Arch Linux, `newvision@10.1.120.53`, code and database under
`/opt/live`. Two units own everything; nothing runs in a shell.
| Unit | Role |
| --- | --- |
| `streamcore-backend.service` | uvicorn on `127.0.0.1:18080`. Also supervises MediaMTX and the ffmpeg transcoders as child processes. |
| `nginx.service` | distro unit. Serves `frontend/dist` and the HLS segments from disk on :80/:443 and proxies `/api`, `/docs`, `/openapi.json` and the HLS fallback to the backend. |
`/opt/live` is expected to be owned by `newvision` — the SQLite file,
`settings.json`, `nodes.json`, `runtime/` and `media/` are all written at runtime.
### One-time setup
```bash
# packages: nginx from pacman; Python deps in a venv (Arch enforces PEP 668,
# so a system-wide pip install is refused); npm only to build the frontend
sudo pacman -Sy --needed nginx npm
python3 -m venv /opt/live/backend/venv
/opt/live/backend/venv/bin/pip install -r /opt/live/backend/requirements.txt
# MediaMTX ships no binary in the repo; drop the release build beside its config
tar -xzf mediamtx_v1.21.2_linux_amd64.tar.gz -C /tmp
install -m 755 /tmp/mediamtx /opt/live/mediamtx/mediamtx
# the frontend is built once; dist/ is gitignored
cd /opt/live/frontend && npm install && npm run build
sudo mkdir -p /etc/nginx/certs/{ecc,rsa} /opt/live/{media,runtime/{hls,replay,logs}}
sudo chown -R newvision:newvision /opt/live
```
### Ports
`8080` is taken by the gitea container on the reference host, so the backend
listens on loopback `:18080` and only nginx is public. MediaMTX keeps its own
ports (`1935` RTMP, `8554` RTSP, `8888` HLS, `8889` WebRTC, `9997` API) and
publishers go to it directly — RTMP is not proxied through nginx.
### Operating it
```bash
systemctl status streamcore-backend
sudo systemctl restart streamcore-backend # restart; MediaMTX comes back with it
sudo journalctl -u streamcore-backend -f # backend + MediaMTX + transcoder logs
sudo systemctl reload nginx # only after editing the config
```
Both units are `enabled`, so a reboot brings the stack up without a login.
### Notes specific to this host
- **No GPU.** `detect_encoder()` probes NVENC/QSV/AMF and falls back to
`libx264`, logging the choice at startup. Expect CPU cost per rendition.
- **nginx file descriptors.** Arch sets only the *hard* `DefaultLimitNOFILE`
(524288) and leaves the soft limit at 1024, which makes nginx clamp
`worker_connections 4096` and warn. `/etc/systemd/system/nginx.service.d/nofile.conf`
pins `LimitNOFILE=65535:65535`. Running `nginx -t` by hand still inherits the
shell's 1024 and prints that warning — it is not the service's limit.
- **A stale `live` stream in the database** makes the lifespan start transcoders
for a publisher that is not there: a few ffmpeg processes spawn, exit, and sit
as zombies. Mark the row `ended` rather than leaving it `live`.
For local development on any platform, 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.