documentation/stream-api/deployment/self-hosting.md

# 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`.
- `TMDB_API_KEY` *(string, recommended)* — TMDB v3 API key for metadata lookups.
- `WORKER_COUNT` *(number, optional)* — Number of cluster workers. Default: available CPU count.
- `ENABLE_DEBUG_ROUTE` *(boolean, optional)* — Enables `/debug/:source`. Keep `false` in production.
- `FALLBACK_BASE` *(string, optional)* — Secondary Stream API URL for failover redirects.
- `IS_HF` *(boolean, optional)* — Enables HuggingFace Spaces compatibility.

---

## Deployment Option 1: Docker

### Dockerfile
```dockerfile
FROM node:20-alpine

WORKDIR /app

RUN apk add --no-cache python3 make g++

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

ENV PORT=7860
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
      - 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 ci --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

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
```