233 lines
10 KiB
Markdown
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. |