Updated documentation

2025-05-29 18:46:40 -05:00
parent 34c446bcfa
commit 729eabf27f
1 changed files with 103 additions and 119 deletions
--- 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 <repo-url>
+# 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 <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
-./scripts/delete_cognito_user.sh <user_pool_id> <username>
+## 📂 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.