Files
documentation/stream-api/deployment/self-hosting.md
2026-11-15 17:34:41 -08:00

168 lines
3.8 KiB
Markdown

# Self-Hosting Stream API
<p class="page-description">Production self-hosting guide for Stream API using Docker, systemd, and Nginx with SSE streaming support.</p>
## Overview
Stream API can be self-hosted on any Linux VPS, home server, or container environment. Self-hosting eliminates shared IP rate limits and allows custom worker tuning.
---
## Configuration
Configure environment variables via a `.env` file in the project root:
- `PORT` *(number, optional)* — Bind port. Default: `7860`.
- `WORKER_COUNT` *(number, optional)* — Number of cluster workers. Default: `1`.
- `TMDB_API_KEY` *(string, recommended)* — TMDB v3 API key for metadata lookups.
- `PROXY_STREAMS` *(boolean, optional)* — Enable local media stream proxying. Default: `true`.
- `PROXY_URL` *(string, optional)* — Base URL of an external proxy server if offloading stream bandwidth.
- `ENABLE_DEBUG_ROUTE` *(boolean, optional)* — Enables `/api/debug/:id`. Keep `false` in production.
- `GA_MEASUREMENT_ID` *(string, optional)* — Google Analytics measurement ID for request metrics.
- `GA_API_SECRET` *(string, optional)* — Google Analytics measurement protocol API secret.
---
## Deployment Option 1: Docker
### Dockerfile
```dockerfile
FROM node:22-slim
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
EXPOSE 7860
CMD ["node", "server.js"]
```
### Docker Compose
```yaml
version: '3.8'
services:
stream-api:
build: .
container_name: vyla-stream-api
restart: unless-stopped
ports:
- "127.0.0.1:7860:7860"
environment:
- PORT=7860
- TMDB_API_KEY=your_tmdb_api_key_here
- WORKER_COUNT=4
- PROXY_STREAMS=true
- ENABLE_DEBUG_ROUTE=false
volumes:
- ./data:/app/data
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```
Start the container:
```bash
docker compose up -d
```
---
## Deployment Option 2: Systemd
### 1. Install
```bash
git clone https://gitlab.com/vyla-entertainment/stream-api.git /opt/stream-api
cd /opt/stream-api
npm install --omit=dev
```
### 2. Service File: `/etc/systemd/system/stream-api.service`
```ini
[Unit]
Description=Vyla Stream API Service
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/stream-api
ExecStart=/usr/bin/node /opt/stream-api/server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=PORT=7860
Environment=TMDB_API_KEY=your_tmdb_api_key_here
Environment=WORKER_COUNT=4
Environment=PROXY_STREAMS=true
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now stream-api
sudo systemctl status stream-api
```
---
## Reverse Proxy: Nginx
Disable proxy buffering so Server-Sent Events (SSE) stream progressively to clients.
Create `/etc/nginx/sites-available/stream-api.conf`:
```nginx
server {
server_name stream-api.yourdomain.com;
client_max_body_size 20M;
location / {
proxy_pass http://127.0.0.1:7860;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;
proxy_read_timeout 90s;
proxy_send_timeout 90s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
listen 80;
}
```
Enable and provision SSL:
```bash
sudo ln -s /etc/nginx/sites-available/stream-api.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d stream-api.yourdomain.com
```
---
## Health Check
Verify the deployment:
```bash
curl -i https://stream-api.yourdomain.com/health
```