Skip to content

README.md

Latest commit

 

History

History
228 lines (186 loc) · 10.6 KB

README.md

File metadata and controls

228 lines (186 loc) · 10.6 KB
IPTV-Manager Logo

IPTV-Manager

A comprehensive IPTV management system with automatic provider synchronization, intelligent category mapping, and multi-user support.

License: MIT

⚠️ DISCLAIMER: This project is for educational purposes only.
IPTV-Manager does not provide any IPTV content or subscriptions. Use your own legal IPTV service.

🚀 Features

Core Functionality

  • Multi-User Management: Support for multiple users with individual channel configurations, secure login, and customizable concurrent stream limits (max connections).
  • Provider Management: Connect to multiple IPTV providers via Xtream Codes API with automatic connection pooling.
  • Category Organization: Drag & drop sorting and visual channel assignment.
  • EPG Integration: Comprehensive Electronic Program Guide (EPG) support with automatic updates.

Advanced Features

  • Automatic Synchronization: Configurable intervals (hourly, daily, weekly) with intelligent category mapping.
  • Provider Connection Pooling: Add the same provider multiple times to create a pool; streams automatically round-robin and fall back to available accounts when connection limits are reached.
  • HDHomeRun Emulation: Emulate HDHomeRun devices for seamless integration with Plex, Emby, and Jellyfin.
  • Shared Links: Create public share links with customizable slugs (short URLs) and expiration dates.
  • Bulk Operations: Optimized bulk category import and deletion for managing large playlists efficiently.
  • VOD & Series Support: Full proxy support for Movies and TV Series.
  • Internationalization: Localized UI (English, German, French, Greek).
  • M3U Playlist Generation: Generate custom M3U playlists for external players.
  • Import/Export: Secure, password-protected data migration.
  • User Backups: Automatically create and manage backups of assigned categories and channels per user.

Security

  • 🛡️ SSRF Protection: Robust validation of upstream URLs (preventing access to private IPs, localhost, cloud metadata).
  • 🔐 Rate Limiting: Tunable protection for general API traffic, brute force (Login), and DoS attacks (Client Logs).
  • 🎫 Secure Authentication: JWT-based auth with session management and Bcrypt password hashing.
  • 🚫 IP Blocking: Configurable IP blocking and whitelisting.
  • 🔒 Security Headers: Comprehensive Helmet.js security headers.

Performance

  • 🔥 Multi-Core Optimization: Node.js Clustering utilizes all CPU cores.
  • ⚡ Optional Redis: High-performance tracking for active streams (recommended for >500 users).
  • 🧵 Worker Threads: Offloads CPU-intensive tasks like EPG mapping.
  • ⚡ Optimized Channel Matching: Fast channel matching algorithms using bitwise signatures.
  • ⚡ Optimized Database Schema: Optimized indices for faster streaming performance and EPG updates.

📋 Requirements

  • Node.js: 24.x+
  • npm: 10.x+
  • SQLite: 3.x (included)
  • MaxMind GeoLite2 License Key: While basic region locking functions work out of the box with the included database, updating the internal GeoIP database requires a free MaxMind License Key. You can get one at maxmind.com and enter it in the WebUI Security Settings. On startup, IPTV-Manager checks MaxMind checksums first and only downloads/rebuilds GeoIP data when an update is available.

Production Deployment

For production environments, it is strongly recommended to set NODE_ENV=production and run the application behind a reverse proxy (like Nginx or Traefik) that handles HTTPS. The application will enforce secure cookies when in production mode.

🐳 Docker Installation (Recommended)

Using Docker Compose

  1. Create docker-compose.yml: 
    services:
  iptv-manager:
    image: ghcr.io/bladestar2105/iptv-manager:latest
    container_name: iptv-manager
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - DATA_DIR=/data
  2. Run docker-compose up -d.
  3. Access at http://localhost:3000.

🔧 Bare Metal / Manual Installation (Debian/Ubuntu)

We provide automated scripts for easy local deployment on Debian and Ubuntu systems. This is ideal for users who do not want to use Docker.

Automated Installation

To install IPTV-Manager as a background systemd service, run the following command as root:

curl -fsSL https://raw.githubusercontent.com/Bladestar2105/IPTV-Manager/main/scripts/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

Automated Updates

To update an existing automated installation, simply navigate to the installation directory and run the update script:

cd /opt/iptv-manager
sudo ./scripts/update.sh

Manual Installation (Development)

  1. Clone repo: git clone https://github.com/Bladestar2105/IPTV-Manager.git
  2. Install: npm install
  3. Configure: cp .env.example .env (edit as needed)
  4. Run: npm start

Proxmox LXC Installation

For Proxmox VE users, you can easily deploy an LXC container running IPTV-Manager. Run the following command directly on your Proxmox Host Shell:

curl -fsSL https://raw.githubusercontent.com/Bladestar2105/IPTV-Manager/main/scripts/proxmox.sh -o proxmox.sh
chmod +x proxmox.sh
./proxmox.sh

Development

  • Linting: npm run lint
  • Testing: npm test
  • Developer notes: docs/DEVELOPMENT.md
  • Configuration reference: docs/CONFIGURATION.md
  • API reference: docs/API_REFERENCE.md

First Time Setup

  • Default Username: admin
  • Default Password: Set by scripts/install.sh and printed at the end of the install (also saved as INITIAL_ADMIN_PASSWORD in /opt/iptv-manager/.env).
  • Important: Change password immediately after login.

CORS Configuration

The application blocks Cross-Origin Resource Sharing (CORS) by default for security. If you need to access the API or streams from another domain (e.g., an external web player), you must configure the ALLOWED_ORIGINS environment variable.

  • Default: Cross-origin requests are blocked (false).
  • Setup: Add ALLOWED_ORIGINS=https://your-web-player.com,https://another-site.com to your .env file.
  • Allow All: Set ALLOWED_ORIGINS=* to allow all domains (⚠️ Not recommended for production).

Rate Limit Tuning

Defaults are intentionally high enough for IPTV clients that make bursty playlist, XMLTV, and Xtream API requests. They can still be tuned via environment variables:

  • API_RATE_LIMIT_MAX (default: 1000 per 60000 ms)
  • AUTH_RATE_LIMIT_MAX (default: 100 per 900000 ms)
  • CLIENT_LOG_RATE_LIMIT_MAX (default: 120 per 3600000 ms)

Each limit also has a matching *_WINDOW_MS variable documented in docs/CONFIGURATION.md.

Stream Session Cleanup (Live / VOD / Series)

To prevent stale sessions from blocking new playback with false Max connections reached / HTTP 403 responses, stream session cleanup is applied across Live TV, Movies, and Series.

Optional tuning via environment variables:

  • STREAM_MAX_AGE_MS (default: 86400000 = 24h)
    Hard safety cap for a single session age. Very old orphan sessions are removed before limit checks.
  • STREAM_INACTIVITY_TIMEOUT_MS (default: 120000 = 2 minutes)
    Inactivity expiry for stalled streams to prevent orphan sessions from blocking new playback.

For most deployments, keep the defaults unless you have a specific operational need.

📸 Screenshots

Login Dashboard
Login Page Dashboard
User Backups Import/Export
User Backups Import/Export
Categories Channels
Category Management Channel Assignment
Sync Logs
Sync Logs
EPG Sources EPG Browse
EPG Sources EPG Browse
EPG Mapping Statistics
EPG Mapping Statistics
Security Xtream Credentials
Security Xtream Credentials
Web Player
Web Player

📚 API Overview

The full route inventory is maintained in docs/API_REFERENCE.md.

Main Endpoint Groups

  • Auth: login, token verification, OTP, password changes, player tokens
  • Users: user CRUD, clone/copy settings, user backups
  • Providers: provider CRUD, sync, channel/category import
  • Categories: category/channel assignment, reorder, bulk actions, mappings
  • EPG: source management, schedule browsing, mapping, auto matching
  • System: settings, security, import/export, sync config, statistics
  • Shares: authenticated share management and public short links

Xtream Codes / Player API

  • GET /player_api.php: Auth & Metadata
  • GET /player_api.php?action=get_live_categories
  • GET /player_api.php?action=get_live_streams&category_id=<id>: Category-scoped live streams
  • GET /player_api.php?action=get_vod_categories
  • GET /player_api.php?action=get_vod_streams&category_id=<id>: Category-scoped VOD
  • GET /player_api.php?action=get_series_categories
  • GET /player_api.php?action=get_series&category_id=<id>: Category-scoped series
  • GET /player_api.php?action=get_short_epg&stream_id=<id>&limit=<n>: Short stream EPG
  • GET /player_api.php?action=get_simple_date_table&stream_id=<id>: Full stream EPG
  • GET /player_api.php?action=get_simple_data_table&stream_id=<id>: Full stream EPG compatibility alias
  • GET /player_api.php?action=get_epg_batch&stream_ids=<ids>&date=<YYYY-MM-DD>: Batched Xtream EPG listings
  • GET /live/:user/:pass/:id.ts: Live Stream
  • GET /movie/:user/:pass/:id.ext: Movie Stream
  • GET /series/:user/:pass/:id.ext: Series Stream
  • GET /xmltv.php: XMLTV EPG, gzip-compressed when requested with Accept-Encoding: gzip

Share + Companion App Integration

  • Share companion integration guide (Xtream/M3U/EPG): docs/SHARE_COMPANION_INTEGRATION.md

HDHomeRun Emulation

  • GET /hdhr/:token/discover.json
  • GET /hdhr/:token/lineup.json
  • GET /hdhr/:token/auto/v:channelId

📄 License

MIT License