FastAPI IPTV Service

This project is a FastAPI application to manage IPTV services, including user registration and authentication. It uses aiosqlite 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

Clone the repository:

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

Install uv: If you don't have uv installed, you can install it via pip:
```
pip install uv
```
Create a virtual environment and install dependencies: uv will automatically create a .venv directory and install dependencies listed in pyproject.toml.
```
uv sync
```
Activate the virtual environment:
- On macOS/Linux: source .venv/bin/activate
- On Windows: .venv\Scripts\activate
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.
```
SUPER_ADMIN_USER=your_super_admin_username
SUPER_ADMIN_PASSWORD=your_super_admin_password
DATABASE_FILENAME=users.db
DATA_PATH=/data
CONTENT_PATH=/content
```
Important Notes:
- For Docker deployments, paths should match volume mounts from the docker run command

Docker Installation

Clone the repository:

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

Build the Docker image:

docker build -t user-registration-service .

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

Ensure you have activated the virtual environment (if installed manually).
Ensure your environment variables (SUPER_ADMIN_USER, SUPER_ADMIN_PASSWORD, DATABASE_FILENAME, DATA_PATH, CONTENT_PATH) are set.
Run the application using uvicorn:
```
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

Ensure you have built the Docker image.
Run the Docker container, mapping ports and volumes:
```
docker run -d \
  --name user-service \
  -p 8000:8000 \
  -v user-service-data:/data \
  -v user-service-content:/content \
  -e SUPER_ADMIN_USER=your_super_admin_username \
  -e SUPER_ADMIN_PASSWORD=your_super_admin_password \
  iptv-server
```
Replace your_super_admin_username and your_super_admin_password with your desired credentials.

Key components:
- -v user-service-data:/data creates/manages a Docker volume for persistent database storage
- -v user-service-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):

docker run -d \
  --name user-service \
  -p 8000:8000 \
  -v ./local/data:/data \
  -v ./local/content:/content \
  -e SUPER_ADMIN_USER=admin \
  -e SUPER_ADMIN_PASSWORD=securepassword \
  user-registration-service

## 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.
* `DATABASE_PATH`: The file path where the SQLite database will be stored. Defaults to `users.db` if not set, but the Dockerfile sets it to `/data/users.db`.

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

7.0 KiB Raw Blame History