mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-12 13:37:20 -05:00
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# Self-host Stream API
|
|
|
|
<p class="page-description">Deploy the optional Stream API when your clients need an HTTP/SSE layer.</p>
|
|
|
|
## Overview
|
|
|
|
Stream API is a **self-hosted Node.js** application that you run on infrastructure you control. It does not provide a public hosted instance. The service runs as a Node.js process, uses in-memory caching, and can fork workers through Node's built-in `cluster` module. No database is required by the service itself.
|
|
|
|
:::callout-warning
|
|
Stream API is self-hosted only. There is no public Vyla streaming endpoint. You only need it when your architecture requires an HTTP/SSE layer; Node.js applications can use [Vyla SDK](/sdk) directly.
|
|
:::
|
|
|
|
## Requirements
|
|
|
|
- Node.js 18 or later
|
|
- A TMDB API key if you want title validation and metadata lookups
|
|
|
|
## Environment variables
|
|
|
|
Create a `.env` file in the project root:
|
|
|
|
```bash
|
|
TMDB_API_KEY=
|
|
PORT=7860
|
|
WORKER_COUNT=1
|
|
ENABLE_DEBUG_ROUTE=false
|
|
PROXY_STREAMS=false
|
|
PROXY_URL=
|
|
|
|
GA_MEASUREMENT_ID=
|
|
GA_API_SECRET=
|
|
```
|
|
|
|
<div class="card">
|
|
<div class="card-title">Variable reference</div>
|
|
<div class="card-body">
|
|
|
|
| Variable | Required | Description |
|
|
| --- | --- | --- |
|
|
| `TMDB_API_KEY` | Yes | Enables TMDB-based ID validation, metadata lookups, and anime detection. Some sources will not work without it. |
|
|
| `GA_MEASUREMENT_ID` / `GA_API_SECRET` | No | Enables Google Analytics event reporting. Leave blank to disable. |
|
|
| `PORT` | No | Port the server listens on. Defaults to `7860`. |
|
|
| `WORKER_COUNT` | No | Number of cluster workers to fork. Defaults to `1` locally. |
|
|
| `ENABLE_DEBUG_ROUTE` | No | Set to `true` to enable `/api/debug/:id`. Keep this `false` in production — it exposes upstream request/response headers and raw source output. |
|
|
| `PROXY_STREAMS` | No | Set to `true` to route stream playback through your own server's `/api` proxy endpoint instead of direct URLs. |
|
|
| `PROXY_URL` | No | An external proxy base URL to use instead of the built-in `/api` proxy. Only used if `PROXY_STREAMS` is enabled. |
|
|
|
|
</div>
|
|
</div>
|
|
|
|
## Installing and running
|
|
|
|
```bash
|
|
git clone https://gitlab.com/vyla-entertainment/stream-api
|
|
cd stream-api
|
|
npm install
|
|
node server.js
|
|
```
|
|
|
|
The server listens on:
|
|
|
|
```
|
|
http://localhost:7860
|
|
```
|
|
|
|
Visit `/health` to confirm it is running and check which sources are currently reachable from your host.
|
|
|
|
## Running with multiple workers
|
|
|
|
Setting `WORKER_COUNT` above `1` forks additional worker processes via `cluster`.
|
|
|
|
The primary process holds a shared in-memory cache (capped at 1500 entries, pruned every 30 seconds) and relays cache reads/writes between workers over IPC, allowing cached stream results to be shared rather than duplicated.
|
|
|
|
```bash
|
|
WORKER_COUNT=4
|
|
node server.js
|
|
```
|
|
|
|
Each worker independently loads source modules and handles outbound requests. Only shared cache operations and concurrency limits are coordinated through the primary process.
|
|
|
|
## Network considerations
|
|
|
|
Several sources are documented in `config.js` as blocked on datacenter IPs. This commonly affects cloud hosting providers and VPS environments.
|
|
|
|
If a source's `getStream` consistently returns nothing from your server but works from a residential connection, the cause is usually upstream blocking based on IP reputation. For the best experience, run Vyla API on a residential connection or use a residential proxy.
|
|
|
|
When running on a local desktop environment, you should have minimal issues with source availability since you're using a residential IP address.
|
|
|
|
## Reverse proxy / TLS
|
|
|
|
The server runs over plain HTTP. For public deployments, place it behind a reverse proxy such as Caddy, Nginx, or Cloudflare Tunnel to terminate TLS and forward requests to the configured `PORT`.
|
|
|
|
CORS is already configured at the application layer with:
|
|
|
|
```
|
|
Access-Control-Allow-Origin: *
|
|
```
|
|
|
|
No additional CORS configuration is required on the proxy.
|
|
|
|
## Verifying your deployment
|
|
|
|
Run these checks in order:
|
|
|
|
1. `GET /health`
|
|
|
|
Confirms the process is running and reports per-source reachability from your host.
|
|
|
|
2. `GET /api/test/155?source=vidrock`
|
|
|
|
Runs a real source resolution using a known TMDB movie ID and returns whether the source succeeded.
|
|
|
|
3. `GET /api/debug/155?source=vidrock`
|
|
|
|
Only available when `ENABLE_DEBUG_ROUTE=true`.
|
|
|
|
Returns request traces, headers, and raw candidate URLs for debugging source failures.
|
|
|
|
:::callout-warning
|
|
Leave `ENABLE_DEBUG_ROUTE` disabled on public deployments. The debug route exposes upstream request information and raw stream URLs, which can leak internal details.
|
|
::: |