ɳTV Backend Setup

ɳTV Backend Setup

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.

---

Related

• 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