Self-Hosting Stream API

Complete production self-hosting guide for Stream API: Docker, Node.js systemd, PM2, and Nginx reverse proxy configuration with SSE streaming support.

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:

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:

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:

docker compose up -d

Deployment Option 2: Direct Node.js & Systemd

1. Installation

# 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:

[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:

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:

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:

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:

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.

5.1 KiB Raw Blame History