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

# Self-Hosting Stream API

<p class="page-description">Complete production self-hosting guide for Stream API: Docker, Node.js systemd, PM2, and Nginx reverse proxy configuration with SSE streaming support.</p>

## Overview

Stream API is designed to be completely self-hostable on any Linux virtual private server (VPS), home server, or Docker container environment. Running your own instance gives you private access, eliminates shared IP rate limits, and allows you to tune worker concurrency to your hardware.

---

## Environment Variables

Configure your environment variables via a `.env` file in the project root:

| Variable | Required | Default | Description |
| :--- | :--- | :--- | :--- |
| `PORT` | Optional | `7860` | HTTP port on which the server binds. |
| `TMDB_API_KEY` | **Recommended** | `""` | The Movie Database v3 API key. Required for scrapers that resolve metadata via IMDb ID or episode titles. |
| `WORKER_COUNT` | Optional | `os.cpus().length` | Number of worker processes to fork in cluster mode. |
| `ENABLE_DEBUG_ROUTE` | Optional | `false` | Enables deep diagnostic traces at `/debug/:source`. Keep `false` in production. |
| `GA_MEASUREMENT_ID` | Optional | `""` | Google Analytics 4 Measurement ID for private usage telemetry. |
| `GA_API_SECRET` | Optional | `""` | Google Analytics 4 Measurement Protocol API Secret. |
| `FALLBACK_BASE` | Optional | `""` | Secondary Stream API instance URL used for failover redirects. |
| `IS_HF` | Optional | `false` | Enables HuggingFace Spaces compatibility constraints. |

---

## Deployment Option 1: Docker (Recommended)

### 1. Dockerfile
Create a `Dockerfile` in the project directory:

```dockerfile
FROM node:20-alpine

WORKDIR /app

# Install native dependencies required for TLS and encryption
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"]
```

### 2. Docker Compose
Create a `docker-compose.yml` file:

```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 in detached mode:
```bash
docker compose up -d
```

---

## Deployment Option 2: Direct Node.js & Systemd

### 1. Installation
```bash
# Clone the repository
git clone https://gitlab.com/vyla-entertainment/stream-api.git /opt/stream-api
cd /opt/stream-api

# Install dependencies
npm ci --omit=dev
```

### 2. Create Systemd Service
Create `/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

# Security Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
```

Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now stream-api
sudo systemctl status stream-api
```

---

## Reverse Proxy: Nginx Configuration

Because Stream API utilizes **Server-Sent Events (SSE)** and large **HLS video streams**, your reverse proxy must disable proxy buffering. Standard buffering will delay SSE events until the buffer fills, breaking progressive playback.

Create an Nginx configuration at `/etc/nginx/sites-available/stream-api.conf`:

```nginx
server {
    server_name stream-api.yourdomain.com;

    # Maximum upload size for DB syncs
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_http_version 1.1;

        # Mandatory for Server-Sent Events (SSE)
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;

        # Keep-Alive & Timeouts for long media streams
        proxy_read_timeout 90s;
        proxy_send_timeout 90s;

        # Forward Client Identifiers for Geo-Token Verification
        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 the configuration and obtain a free SSL certificate via Certbot:
```bash
sudo ln -s /etc/nginx/sites-available/stream-api.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Install Let's Encrypt SSL
sudo certbot --nginx -d stream-api.yourdomain.com
```

---

## Verifying Your Deployment

Once deployed, verify the installation by testing the `/health` endpoint:

```bash
curl -i https://stream-api.yourdomain.com/health
```

You should receive an HTTP 200 (or 207) with JSON detailing the cluster status, cache count, and source probe results.