iptv-server/README.md

# 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`.

## Features

* 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`.

## Prerequisites

* Python 3.10+
* uv (for manual installation)
* Docker (for Docker installation)

## Installation

You can install and run the project either manually or using Docker.

### Manual Installation

1. **Clone the repository:**

    ```bash
    git clone <repository-url>
    cd <repository-directory>
    ```

2. **Install `uv`:**
    If you don't have `uv` installed, you can install it via pip:

    ```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.

    ```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
    ```

    **Important Notes:**
    * For Docker deployments, paths should match volume mounts from the `docker run` command

### Docker Installation

1. **Clone the repository:**

    ```bash
    git clone <repository-url>
    cd <repository-directory>
    ```

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:

    ```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 \
      iptv-server
    ```

    Replace `your_super_admin_username` and `your_super_admin_password` with your desired credentials. 

    Key components:
    * `-v iptv-server-content:/content` ensures content directory persistence
    * Environment variables match those expected by the application (defined in Dockerfile)

    The application will be available at `http://localhost:8000` (or your Docker host's IP).

**For bind mounts instead of named volumes** (useful for development):

```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


## Usage

The API documentation will be available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc) once the server is running.

* **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.

    ```json
    {
      "username": "newuser",
      "password": "securepassword123"
    }
    ```

* **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.

## Configuration

The application is configured using the following environment variables:

* `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.

## 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`).

*(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).*