ɳTV Backend Setup

ɳTV Backend Setup — ɳSelf documentation.

This page is a reference for setting up the ɳSelf backend that powers ɳTV’s library, streaming, EPG, and sync features. If you want a step-by-step walkthrough, see Getting Started instead.

What the Backend Provides

ɳTV’s backend features are powered by the ɳSelf CLI and the ɳTV plugin bundle. Without a backend, ɳTV works as an IPTV M3U player only.

With the backend running the ɳTV bundle, you get:

A scanned and indexed media library backed by PostgreSQL
Server-side HLS/DASH streaming with adaptive bitrate
TMDB metadata enrichment (poster art, descriptions, cast, ratings)
EPG for live channels
Cross-device progress sync via Hasura GraphQL
Media acquisition and encoding via optional plugins

Prerequisites

ɳSelf CLI (latest stable) : Installation guide
Docker Desktop (macOS / Windows) or Docker Engine (Linux)
An nself license key with the ɳTV bundle entitlement ($0.99/mo per F06) : get one at nself.org
A directory you can dedicate to the backend (e.g., ~/stacks/nself)

Plugin Reference

Required Paid Plugins

These plugins require a valid ɳTV bundle license key.

Plugin	Purpose	Notes
`streaming`	Library API, HLS/DASH segments, progress sync	Core, required for all library features
`stream-gateway`	Stream URL routing and access control	Routes playback requests from the app
`epg`	Electronic Program Guide for live channels	Only needed if using live TV
`tmdb`	TMDB metadata lookup and poster art	Requires a free TMDB API key

Free Plugins

These plugins do not require a license key.

Plugin	Purpose
`torrent-manager`	BitTorrent client for media acquisition
`content-acquisition`	Automated download and discovery orchestration
`subtitle-manager`	Subtitle search, download, and sync

Optional Paid Plugins

Plugin	Purpose
`media-processing`	Server-side encoding pipeline (Rust, hardware-accelerated)
`recording`	DVR recording from live streams (pairs with `epg`)
`game-metadata`	Game library metadata lookup (IGDB)
`vpn`	VPN integration for privacy-conscious downloading

Setup Steps

Step 1: Initialize the Stack

mkdir ntv-backend && cd ntv-backend
nself init

nself init prompts for a project name, domain, and environment. For a local development setup, use localhost and accept defaults.

Step 2: Set Your License Key

nself license set <your-nself-pro-key>

The CLI validates the key against ping.nself.org/license/validate. Without a valid key, paid plugins refuse to install.

Check key status at any time:

nself license status

Step 3: Install Plugins

Required minimum:

nself plugin install streaming stream-gateway epg tmdb

Free companions:

nself plugin install torrent-manager content-acquisition subtitle-manager

Optional:

nself plugin install media-processing recording

Step 4: Configure Environment Variables

Edit .env.local in your backend directory to set plugin-specific values.

Required:

Variable	Description
`TMDB_API_KEY`	Your TMDB API key, get a free one at themoviedb.org
`MEDIA_PATH`	Absolute path to the directory where your media files live

Common tuning values:

Variable	Default	Description
`STREAMING_HLS_SEGMENT_DURATION`	`6`	HLS segment length in seconds
`STREAMING_MAX_BITRATE`	unlimited	Cap on adaptive bitrate
`EPG_PROVIDER`	`xmltv`	EPG source format (`xmltv` or `json`)
`TMDB_LANGUAGE`	`en-US`	Locale for titles and descriptions
`LIBRARY_SCAN_INTERVAL_HOURS`	`6`	Backend rescan cadence
`SYNC_PROGRESS_INTERVAL_MS`	`10000`	App-side progress report cadence

Full env var inventory: F09-ENV-VAR-INVENTORY in the PPI SPORT directory.

Step 5: Build and Start

nself build
nself start

nself build generates the docker-compose.yml from your plugin configuration. Never hand-edit that file.

nself start brings up all services: PostgreSQL, Hasura, Auth, Nginx, and all installed ɳTV plugins.

Check everything is running:

nself status

All services must show as Running before the ɳTV app can connect.

Step 6: Verify the Schema

nself doctor

Confirms all plugins have migrated their tables. The ɳTV app’s first-run health check queries the same schema.

You can also verify the streaming plugin directly:

curl http://localhost:8000/streaming/library \
  -H "Authorization: Bearer <your-admin-token>"

Expected: a JSON response (empty array if no media yet).

Staging and Production Deployment

To deploy the backend to a remote server:

nself deploy staging   # deploy to staging
nself deploy prod      # deploy to production

The ɳTV Flutter app can point to any reachable backend URL. Update the Backend URL in Settings to switch between local, staging, and prod.

Troubleshooting

Symptom	Cause	Fix
”License invalid”	Key is wrong, expired, or `ping.nself.org` is unreachable	Check `nself license status`. Verify the key in your nself.org account.
”Plugin missing schema”	Migration was skipped or rolled back	Run `nself db sync`. If still failing, file an issue against the plugin.
”ɳTV bundle entitlement not granted”	Your tier does not include the ɳTV bundle	Upgrade at nself.org or add the ɳTV bundle to your subscription.
Streaming plugin not reachable	Services not fully started	Run `nself status`. All services must be Running.
Media not appearing in library	Scan not triggered	Run `nself plugin run media-processing scan` (requires `media-processing` plugin).
No poster art	`TMDB_API_KEY` missing or invalid	Set `TMDB_API_KEY` in `.env.local` and restart: `nself restart tmdb`.

Getting Started: step-by-step setup walkthrough
ɳTV overview: architecture and platform matrix
Plugin system: how the nself plugin system works
ɳSelf CLI reference: nself plugin install command reference