Self-Hosting Stream API

Production self-hosting guide for Stream API using Docker, systemd, and Nginx with SSE streaming support.

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

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

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:

docker compose up -d

Deployment Option 2: Systemd

1. Install

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`

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

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:

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:

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:

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

3.6 KiB Raw Blame History