From 729eabf27f15ff4aab4e6afb5edd792a8d4e79b8 Mon Sep 17 00:00:00 2001 From: Stefano Date: Thu, 29 May 2025 18:46:40 -0500 Subject: [PATCH] Updated documentation --- README.md | 222 +++++++++++++++++++++++++----------------------------- 1 file changed, 103 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index 46e3b82..96e0f14 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,149 @@ # IPTV Manager Service -An automated IPTV playlist and EPG manager service deployed on AWS infrastructure using CDK. +A FastAPI-based service for managing IPTV playlists and channel priorities. The application provides secure endpoints for user authentication, channel management, and playlist generation. -## Overview +## โœจ Features -This project provides a service for automatically updating IPTV playlists and Electronic Program Guide (EPG) data. It runs on AWS infrastructure with: +- **JWT Authentication**: Secure login using AWS Cognito +- **Channel Management**: CRUD operations for IPTV channels +- **Playlist Generation**: Create M3U playlists with channel priorities +- **Stream Monitoring**: Background checks for channel availability +- **Priority Management**: Set channel priorities for playlist ordering -- EC2 instance for hosting the application -- RDS PostgreSQL database for data storage -- Amazon Cognito for user authentication -- HTTPS support via Let's Encrypt -- Domain management via FreeDNS +## ๐Ÿ› ๏ธ Technology Stack -## Prerequisites +- **Backend**: Python 3.11, FastAPI +- **Database**: PostgreSQL (SQLAlchemy ORM) +- **Authentication**: AWS Cognito +- **Infrastructure**: AWS CDK (API Gateway, Lambda, RDS) +- **Testing**: Pytest with 85%+ coverage +- **CI/CD**: Pre-commit hooks, Alembic migrations -- AWS CLI installed and configured -- Python 3.12 or later -- Node.js v22.15 or later for AWS CDK -- Docker and Docker Compose for local development +## ๐Ÿš€ Getting Started -## Local Development +### Prerequisites -1. Clone the repository: +- Python 3.11+ +- Docker +- AWS CLI (for deployment) + +### Installation ```bash -git clone +# Clone repository +git clone https://github.com/your-repo/iptv-manager-service.git cd iptv-manager-service + +# Setup environment +python -m venv venv +source venv/bin/activate +pip install -r requirements.txt +cp .env.example .env # Update with your values + +# Run installation script +./scripts/install.sh ``` -2. Copy the example environment file: - -```bash -cp .env.example .env -``` - -3. Add your configuration to `.env`: - -``` -FREEDNS_User=your_freedns_username -FREEDNS_Password=your_freedns_password -DOMAIN_NAME=your.domain.name -SSH_PUBLIC_KEY=your_ssh_public_key -REPO_URL=repository_url -LETSENCRYPT_EMAIL=your_email -``` - -4. Start the local development environment: +### Running Locally ```bash +# Start development environment ./scripts/start_local_dev.sh -``` -5. Stop the local environment: - -```bash +# Stop development environment ./scripts/stop_local_dev.sh ``` -## Deployment +## โ˜๏ธ AWS Deployment -### Initial Deployment - -1. Ensure your AWS credentials are configured: - -```bash -aws configure -``` - -2. Install dependencies: - -```bash -pip install -r requirements.txt -``` - -3. Deploy the infrastructure: +The infrastructure is defined in CDK. Use the provided scripts: ```bash +# Deploy AWS infrastructure ./scripts/deploy.sh + +# Destroy AWS infrastructure +./scripts/destroy.sh + +# Create Cognito test user +./scripts/create_cognito_user.sh + +# Delete Cognito user +./scripts/delete_cognito_user.sh ``` -The deployment script will: +Key AWS components: -- Create/update the CloudFormation stack using CDK -- Configure the EC2 instance with required software -- Set up HTTPS using Let's Encrypt -- Configure the domain using FreeDNS +- API Gateway +- Lambda functions +- RDS PostgreSQL +- Cognito User Pool -### Continuous Deployment +## ๐Ÿค– Continuous Integration/Deployment -The project includes a Gitea workflow (`.gitea/workflows/aws_deploy_on_push.yml`) that automatically: +This project includes a Gitea Actions workflow (`.gitea/workflows/deploy.yml`) for automated deployment to AWS. The workflow is fully compatible with GitHub Actions and can be easily adapted by: -- Deploys infrastructure changes -- Updates the application on EC2 instances -- Restarts the service +1. Placing the workflow file in the `.github/workflows/` directory +2. Setting up the required secrets in your CI/CD environment: + - `AWS_ACCESS_KEY_ID` + - `AWS_SECRET_ACCESS_KEY` + - `AWS_DEFAULT_REGION` -## Infrastructure +The workflow automatically deploys the infrastructure and application when changes are pushed to the main branch. -The AWS infrastructure is defined in `infrastructure/stack.py` and includes: +## ๐Ÿ“š API Documentation -- VPC with public subnets -- EC2 t2.micro instance (Free Tier eligible) -- RDS PostgreSQL database (db.t3.micro) -- Security groups for EC2 and RDS -- Elastic IP for the EC2 instance -- Cognito User Pool for authentication -- IAM roles and policies for EC2 instance access +Access interactive docs at: -## User Management +- Swagger UI: `http://localhost:8000/docs` +- ReDoc: `http://localhost:8000/redoc` -### Creating Users +### Key Endpoints -To create a new user in Cognito: +| Endpoint | Method | Description | +| ------------- | ------ | --------------------- | +| `/auth/login` | POST | User authentication | +| `/channels` | GET | List all channels | +| `/playlist` | GET | Generate M3U playlist | +| `/priorities` | POST | Set channel priority | + +## ๐Ÿงช Testing + +Run the full test suite: ```bash -./scripts/create_cognito_user.sh --admin <= optional for defining an admin user +pytest ``` -### Deleting Users +Test coverage includes: -To delete a user from Cognito: +- Authentication workflows +- Channel CRUD operations +- Playlist generation logic +- Stream monitoring +- Database operations -```bash -./scripts/delete_cognito_user.sh +## ๐Ÿ“‚ Project Structure + +```txt +iptv-manager-service/ +โ”œโ”€โ”€ app/ # Core application +โ”‚ โ”œโ”€โ”€ auth/ # Cognito authentication +โ”‚ โ”œโ”€โ”€ iptv/ # Playlist logic +โ”‚ โ”œโ”€โ”€ models/ # Database models +โ”‚ โ”œโ”€โ”€ routers/ # API endpoints +โ”‚ โ”œโ”€โ”€ utils/ # Helper functions +โ”‚ โ””โ”€โ”€ main.py # App entry point +โ”œโ”€โ”€ infrastructure/ # AWS CDK stack +โ”œโ”€โ”€ docker/ # Docker configs +โ”œโ”€โ”€ scripts/ # Deployment scripts +โ”œโ”€โ”€ tests/ # Comprehensive tests +โ”œโ”€โ”€ alembic/ # Database migrations +โ”œโ”€โ”€ .gitea/ # Gitea CI/CD workflows +โ”‚ โ””โ”€โ”€ workflows/ +โ””โ”€โ”€ ... # Config files ``` -## Architecture +## ๐Ÿ“ License -The application is structured as follows: - -```bash -app/ -โ”œโ”€โ”€ auth/ # Authentication modules -โ”œโ”€โ”€ iptv/ # IPTV and EPG processing -โ”œโ”€โ”€ models/ # Database models -โ””โ”€โ”€ utils/ # Utility functions - -infrastructure/ # AWS CDK infrastructure code -docker/ # Docker configuration for local development -scripts/ # Utility scripts for deployment and management -``` - -## Environment Variables - -The following environment variables are required: - -| Variable | Description | -| ----------------- | ------------------------------------ | -| FREEDNS_User | FreeDNS username | -| FREEDNS_Password | FreeDNS password | -| DOMAIN_NAME | Your domain name | -| SSH_PUBLIC_KEY | SSH public key for EC2 access | -| REPO_URL | Repository URL | -| LETSENCRYPT_EMAIL | Email for Let's Encrypt certificates | - -## Security Notes - -- The EC2 instance has appropriate IAM permissions for: - - EC2 instance discovery - - SSM command execution - - RDS access - - Cognito user management -- All database credentials are stored in AWS Secrets Manager -- HTTPS is enforced using Let's Encrypt certificates -- Access is restricted through Security Groups +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.