Updated documentation
All checks were successful
AWS Deploy on Push / build (push) Successful in 1m8s
All checks were successful
AWS Deploy on Push / build (push) Successful in 1m8s
This commit is contained in:
222
README.md
222
README.md
@@ -1,165 +1,149 @@
|
|||||||
# IPTV Manager Service
|
# 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
|
## 🛠️ Technology Stack
|
||||||
- RDS PostgreSQL database for data storage
|
|
||||||
- Amazon Cognito for user authentication
|
|
||||||
- HTTPS support via Let's Encrypt
|
|
||||||
- Domain management via FreeDNS
|
|
||||||
|
|
||||||
## 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
|
## 🚀 Getting Started
|
||||||
- Python 3.12 or later
|
|
||||||
- Node.js v22.15 or later for AWS CDK
|
|
||||||
- Docker and Docker Compose for local development
|
|
||||||
|
|
||||||
## Local Development
|
### Prerequisites
|
||||||
|
|
||||||
1. Clone the repository:
|
- Python 3.11+
|
||||||
|
- Docker
|
||||||
|
- AWS CLI (for deployment)
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <repo-url>
|
# Clone repository
|
||||||
|
git clone https://github.com/your-repo/iptv-manager-service.git
|
||||||
cd iptv-manager-service
|
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:
|
### Running Locally
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Start development environment
|
||||||
./scripts/start_local_dev.sh
|
./scripts/start_local_dev.sh
|
||||||
```
|
|
||||||
|
|
||||||
5. Stop the local environment:
|
# Stop development environment
|
||||||
|
|
||||||
```bash
|
|
||||||
./scripts/stop_local_dev.sh
|
./scripts/stop_local_dev.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
## Deployment
|
## ☁️ AWS Deployment
|
||||||
|
|
||||||
### Initial Deployment
|
The infrastructure is defined in CDK. Use the provided scripts:
|
||||||
|
|
||||||
1. Ensure your AWS credentials are configured:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
aws configure
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Install dependencies:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Deploy the infrastructure:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Deploy AWS infrastructure
|
||||||
./scripts/deploy.sh
|
./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
|
- API Gateway
|
||||||
- Configure the EC2 instance with required software
|
- Lambda functions
|
||||||
- Set up HTTPS using Let's Encrypt
|
- RDS PostgreSQL
|
||||||
- Configure the domain using FreeDNS
|
- 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
|
1. Placing the workflow file in the `.github/workflows/` directory
|
||||||
- Updates the application on EC2 instances
|
2. Setting up the required secrets in your CI/CD environment:
|
||||||
- Restarts the service
|
- `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
|
Access interactive docs at:
|
||||||
- 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
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
./scripts/create_cognito_user.sh <user_pool_id> <username> <password> --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
|
## 📂 Project Structure
|
||||||
./scripts/delete_cognito_user.sh <user_pool_id> <username>
|
|
||||||
|
```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:
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||||
|
|
||||||
```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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user