mirror of
https://github.com/sfiorini/iptv-server.git
synced 2026-04-09 07:50:45 +00:00
Update README. Minor bug fix to index.html
This commit is contained in:
196
README.md
196
README.md
@@ -1,26 +1,29 @@
|
||||
# FastAPI IPTV Service
|
||||
|
||||
This project is a FastAPI application to manage IPTV services, including user registration and authentication. It uses `redis` for a lightweight database, `passlib` for password hashing, and `uvicorn` as the ASGI server. It's designed with containerization in mind using Docker and manages dependencies with `uv`.
|
||||
A FastAPI application for managing IPTV content delivery, including playlist and EPG management, user authentication, and content serving. It uses Redis for user management, Vercel Blob Storage for content storage, and provides a secure way to serve IPTV playlists and EPG files.
|
||||
|
||||
## Features
|
||||
|
||||
* IPTV playlist (.m3u/.m3u8) and EPG (.xml/.xml.gz) file hosting
|
||||
* Secure content delivery with user authentication
|
||||
* Admin interface for content and user management
|
||||
* Health check endpoint (`/health`)
|
||||
* Admin-only user registration endpoint (`/admin/register`) using Basic Authentication for the superadmin.
|
||||
* Basic user authentication mechanism (though the user endpoint details are not fully provided).
|
||||
* Lightweight SQLite database for user storage.
|
||||
* Dockerized deployment readiness.
|
||||
* Dependency management with `uv`.
|
||||
* Interactive API documentation
|
||||
* Redis-based user management
|
||||
* Vercel Blob Storage integration
|
||||
* Dockerized deployment support
|
||||
* Static frontend for service information
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Python 3.10+
|
||||
* uv (for manual installation)
|
||||
* Docker (for Docker installation)
|
||||
* Python 3.12+
|
||||
* uv (for dependency management)
|
||||
* Docker (optional)
|
||||
* Redis instance (local or Upstash)
|
||||
* Vercel Blob Storage account
|
||||
|
||||
## Installation
|
||||
|
||||
You can install and run the project either manually or using Docker.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. **Clone the repository:**
|
||||
@@ -30,148 +33,111 @@ You can install and run the project either manually or using Docker.
|
||||
cd <repository-directory>
|
||||
```
|
||||
|
||||
2. **Install `uv`:**
|
||||
If you don't have `uv` installed, you can install it via pip:
|
||||
2. **Install dependencies:**
|
||||
|
||||
```bash
|
||||
pip install uv
|
||||
```
|
||||
|
||||
3. **Create a virtual environment and install dependencies:**
|
||||
`uv` will automatically create a `.venv` directory and install dependencies listed in `pyproject.toml`.
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
Activate the virtual environment:
|
||||
* On macOS/Linux: `source .venv/bin/activate`
|
||||
* On Windows: `.venv\Scripts\activate`
|
||||
|
||||
4. **Configure Environment Variables:**
|
||||
The application requires environment variables for superadmin credentials and the database path. Create a `.env` file in the project root or set them in your shell environment.
|
||||
3. **Configure Environment Variables:**
|
||||
Create a `.env` file:
|
||||
|
||||
```env
|
||||
SUPER_ADMIN_USER=your_super_admin_username
|
||||
SUPER_ADMIN_PASSWORD=your_super_admin_password
|
||||
KV_REST_API_TOKEN="REdIslONglOnGtOkEn"
|
||||
KV_REST_API_URL="https://redis-url.upstash.io"
|
||||
CONTENT_PATH=/content
|
||||
SUPER_ADMIN_USER=admin
|
||||
SUPER_ADMIN_PASSWORD=adminpassword
|
||||
USE_LOCAL_REDIS=true
|
||||
LOCAL_REDIS_URL=redis://localhost:6379
|
||||
KV_REST_API_TOKEN=your_upstash_token
|
||||
KV_REST_API_URL=your_upstash_url
|
||||
BLOB_READ_WRITE_TOKEN=your_vercel_blob_token
|
||||
CONTENT_PATH=./content
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
* For Docker deployments, paths should match volume mounts from the `docker run` command
|
||||
|
||||
### Docker Installation
|
||||
|
||||
1. **Clone the repository:**
|
||||
1. **Build the image:**
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd <repository-directory>
|
||||
docker build -t iptv-server .
|
||||
```
|
||||
|
||||
2. **Build the Docker image:**
|
||||
|
||||
```bash
|
||||
docker build -t user-registration-service .
|
||||
```
|
||||
|
||||
3. **Configure Environment Variables:**
|
||||
You can pass environment variables directly when running the container or use a `.env` file with `docker run --env-file .env ...`.
|
||||
|
||||
## Running the Application
|
||||
|
||||
### Running Manually
|
||||
|
||||
1. Ensure you have activated the virtual environment (if installed manually).
|
||||
2. Ensure your environment variables (`SUPER_ADMIN_USER`, `SUPER_ADMIN_PASSWORD`, `CONTENT_PATH`) are set.
|
||||
3. Run the application using uvicorn:
|
||||
|
||||
```bash
|
||||
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload --workers 2
|
||||
```
|
||||
|
||||
The application will be available at `http://0.0.0.0:8000`.
|
||||
|
||||
*(Note: The `if __name__ == "__main__":` block in `src/main.py` runs uvicorn on port 8080, but the `CMD` in the Dockerfile and the manual command above uses 8000. The command line argument takes precedence.)*
|
||||
|
||||
### Running with Docker
|
||||
|
||||
1. Ensure you have built the Docker image.
|
||||
2. Run the Docker container, mapping ports and volumes:
|
||||
2. **Run with Docker:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name iptv-server \
|
||||
-p 8000:8000 \
|
||||
-v iptv-server-content:/content \
|
||||
-e SUPER_ADMIN_USER=your_super_admin_username \
|
||||
-e SUPER_ADMIN_PASSWORD=your_super_admin_password \
|
||||
-e KV_REST_API_TOKEN=REdIslONglOnGtOkEn \
|
||||
-e KV_REST_API_URL=https://redis-url.upstash.io \
|
||||
-v ./content:/content \
|
||||
--env-file .env \
|
||||
iptv-server
|
||||
```
|
||||
|
||||
Replace `your_super_admin_username` and `your_super_admin_password` with your desired credentials.
|
||||
## API Endpoints
|
||||
|
||||
Key components:
|
||||
* `-v iptv-server-content:/content` ensures content directory persistence
|
||||
* Environment variables match those expected by the application (defined in Dockerfile)
|
||||
### Admin Endpoints
|
||||
|
||||
The application will be available at `http://localhost:8000` (or your Docker host's IP).
|
||||
* `POST /admin/register` - Register new users (superadmin only)
|
||||
* `DELETE /admin/users/{username}` - Delete users (superadmin only)
|
||||
* `POST /admin/playlist` - Upload playlist files
|
||||
* `DELETE /admin/playlist/{filename}` - Delete playlist files
|
||||
* `POST /admin/epg` - Upload EPG files
|
||||
* `DELETE /admin/epg/{filename}` - Delete EPG files
|
||||
|
||||
**For bind mounts instead of named volumes** (useful for development):
|
||||
### Content Endpoints
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name iptv-server \
|
||||
-p 8000:8000 \
|
||||
-v ./local/content:/content \
|
||||
-e SUPER_ADMIN_USER=admin \
|
||||
-e SUPER_ADMIN_PASSWORD=securepassword \
|
||||
iptv-server
|
||||
* `GET /content/playlist/{filename}` - Access playlist files (authenticated)
|
||||
* `GET /content/epg/{filename}` - Access EPG files (authenticated)
|
||||
|
||||
### Other Endpoints
|
||||
|
||||
## Usage
|
||||
* `GET /health` - Service health check
|
||||
* `GET /docs` - Swagger UI documentation
|
||||
* `GET /redoc` - ReDoc documentation
|
||||
|
||||
The API documentation will be available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc) once the server is running.
|
||||
## Authentication
|
||||
|
||||
* **GET /health**: Checks the application status. Returns `{"status": "healthy"}` if running.
|
||||
* **POST /admin/register**: Registers a new user. This endpoint is protected by Basic Authentication. You must authenticate using the `SUPER_ADMIN_USER` and `SUPER_ADMIN_PASSWORD` configured via environment variables. The request body should be a JSON object containing the `username` and `password` of the new user to register.
|
||||
The service uses HTTP Basic Authentication with two levels:
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "securepassword123"
|
||||
}
|
||||
```
|
||||
1. **Superadmin Authentication**: Required for admin operations (user management, content uploads)
|
||||
2. **User Authentication**: Required for accessing content
|
||||
|
||||
* **GET /user**: (Details not fully provided in the code) This endpoint is included via a router but its specific functionality and authentication requirements are not shown in the provided code snippets. Based on the `get_current_user` function, it likely requires basic user authentication using credentials stored in the database.
|
||||
Authentication can be provided via:
|
||||
|
||||
## Configuration
|
||||
* HTTP Basic Auth headers
|
||||
* Query parameters (for IPTV player compatibility)
|
||||
|
||||
The application is configured using the following environment variables:
|
||||
## Storage
|
||||
|
||||
* `SUPER_ADMIN_USER`: The username for the superadmin Basic Authentication.
|
||||
* `SUPER_ADMIN_PASSWORD`: The password for the superadmin Basic Authentication.
|
||||
* `KV_REST_API_TOKEN`: The token for interacting with Upstash\'s Redis service.
|
||||
* `KV_REST_API_URL`: The URL for Upstash\'s Redis service.
|
||||
* **User Data**: Stored in Redis (local or Upstash)
|
||||
* **Content Files**: Stored in Vercel Blob Storage
|
||||
* **Static Files**: Served from local filesystem
|
||||
|
||||
## Project Structure
|
||||
|
||||
* `Dockerfile`: Defines the Docker image build process.
|
||||
* `pyproject.toml`: Manages project dependencies using `uv`.
|
||||
* `src/`: Contains the main application source code.
|
||||
* `main.py`: The main FastAPI application instance, includes routers and defines the entry point for uvicorn.
|
||||
* `auth.py`: Contains authentication logic (though the provided snippet seems incomplete and potentially duplicated with `utils/auth.py`).
|
||||
* `database.py`: Handles database connection setup and table creation (again, potentially duplicated with `utils/database.py`).
|
||||
* `routers/`: Contains API route definitions.
|
||||
* `admin.py`: Defines admin-specific routes, like `/admin/register`.
|
||||
* `user.py`: (Content not provided) Placeholder for user-specific routes.
|
||||
* `utils/`: Contains utility functions.
|
||||
* `auth.py`: Contains utility functions for authentication (like `verify_superadmin`).
|
||||
* `database.py`: Contains utility functions for database interaction (like `get_db`).
|
||||
* `models/`: (Content not provided, but implied by `models.models.User`) Likely contains Pydantic models for data validation (e.g., the User model used in `/admin/register`).
|
||||
```sh
|
||||
src/
|
||||
├── main.py # Application entry point
|
||||
├── config.py # Configuration management
|
||||
├── models/ # Data models
|
||||
├── routers/ # API routes
|
||||
│ ├── admin.py # Admin endpoints
|
||||
│ └── content.py # Content serving endpoints
|
||||
├── static/ # Static frontend files
|
||||
└── utils/ # Utility functions
|
||||
├── admin.py # Admin operations
|
||||
├── auth.py # Authentication
|
||||
└── database.py # Database operations
|
||||
```
|
||||
|
||||
*(Note: There appear to be duplicate `auth.py` and `database.py` files at `src/` and `src/utils/`. You should consolidate these into `src/utils/` and update imports accordingly for a cleaner structure).*
|
||||
## Development
|
||||
|
||||
Run the development server:
|
||||
|
||||
```bash
|
||||
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See LICENSE file for details.
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
index.html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
|
||||
Reference in New Issue
Block a user