IPTV Management System

Status: Actively in development ⚠️

A modern IPTV management system that leverages AWS Cognito for secure user authentication and provides tools for EPG generation, stream validation, and cloud deployment via AWS CDK. It automatically provisions infrastructure, including an EC2 instance running the application behind Nginx, and uses acme.sh with FreeDNS for automated SSL certificate management.

Key Features

✅ Implemented

• User Authentication:

  • AWS Cognito integration for secure user sign-in
  • JWT token generation & validation
  • Role-based access control (RBAC) with the require_roles decorator (Endpoints include both general and admin-protected routes)

• Stream & EPG Management:

  • EPG generation from M3U8 playlists (app/iptv/createEpg.py)
  • Playlist creation utility (app/iptv/createPlaylist.py)
  • Stream validation tooling (app/utils/check_streams.py)

• Deployment & Infrastructure:

  • Infrastructure provisioning using AWS CDK (app.py, infrastructure/stack.py)
  • Automated SSL certificate provisioning using acme.sh and FreeDNS DNS API.
  • Nginx configured as a reverse proxy with SSL termination.
  • Deployment scripts to deploy/destroy the stack and update running instances (scripts/deploy.sh, scripts/destroy.sh)
  • Environment configuration driven by a .env file (.env, .env.example)
  • Gitea Actions workflow for automated deployment on push (.gitea/workflows/aws_deploy_on_push.yml), compatible with minor changes for GitHub Actions.

🛠️ In Progress

• User management interface and additional API endpoints
• Automated EPG updates and playlist management endpoints
• Refresh token implementation and enhanced security features
• Comprehensive API documentation

Installation & Deployment

Prerequisites

• AWS Account and configured AWS CLI credentials.
• Node.js and npm installed (for AWS CDK).
• Python 3.8+ and pip installed.
• uv installed (pip install uv).
• A domain name hosted on FreeDNS.
• FreeDNS API credentials (username and password).
• An email address for Let's Encrypt registration.
• An SSH public key to access the EC2 instance.

Local Setup

1. Clone the repository:

   git clone [repository-url]
   cd iptv-updater-aws
   

2. Set up the virtual environment:

   uv venv .venv
   source .venv/bin/activate
   uv pip install -r requirements.txt
   

3. Configure environment variables:

   Copy .env.example to .env and update the credentials and domain information. You will need to provide:

   • FREEDNS_User: Your FreeDNS username.
   • FREEDNS_Password: Your FreeDNS password.
   • DOMAIN_NAME: Your domain name registered with FreeDNS.
   • SSH_PUBLIC_KEY: Your SSH public key string.
   • REPO_URL: The URL of this git repository.
   • LETSENCRYPT_EMAIL: The email address for Let's Encrypt notifications.

Deploying Infrastructure

The project uses AWS CDK to provision the required AWS resources.

1. Install dependencies and CDK globally:

   ./install.sh
   

2. Deploy the stack:

   ./scripts/deploy.sh
   

   This script will read variables from your .env file, synthesize the CDK stack, deploy it to AWS, and then use AWS SSM to update the application code on the newly created EC2 instance. The EC2 instance's userdata script will handle the installation of dependencies, Nginx, acme.sh, and the initial certificate provisioning using the FreeDNS API credentials passed via environment variables.

3. Update application on running instances:

   The deployment script (scripts/deploy.sh) automatically updates the application code on running instances after the initial deployment. You can re-run this script to pull the latest code and restart the service without destroying and recreating the infrastructure.

4. Destroy the stack:

   ./scripts/destroy.sh
   

   This script will read variables from your .env file and destroy all resources created by the CDK stack.

Automated Deployment (Gitea Actions)

The repository includes a Gitea Actions workflow definition at .gitea/workflows/aws_deploy_on_push.yml. This workflow is triggered on pushes to the main branch and automates the deployment process using AWS CDK and SSM. This workflow is largely compatible with GitHub Actions with minimal modifications.

To use the automated deployment:

1. Configure the required secrets (AWS_ACCESS_KEY, AWS_SECRET_KEY, FREEDNS_USER, FREEDNS_PASSWORD, DOMAIN_NAME, SSH_PUBLIC_KEY, REPO_URL, LETSENCRYPT_EMAIL) in your Gitea repository settings.
2. Push changes to the main branch.

Usage

• API Endpoints: The application will be accessible via HTTPS on your configured domain name.

  • Sign-in: /signin
  • Protected endpoints: /protected and /protected_admin

• EPG & Playlist Generation:

  • Create playlists using app/iptv/createPlaylist.py
  • Generate EPG data using app/iptv/createEpg.py

• Stream Validation:

  • Validate stream URLs using the utility (app/utils/check_streams.py)

Notes

• This project is under active development. Expect additional functionality and improvements in upcoming releases.
• For deployment details and troubleshooting, refer to the deployment scripts and AWS CDK documentation.
• Ensure your FreeDNS API credentials and domain name are correctly configured in the .env file for acme.sh to function correctly.