First commit

README.md

@@ -0,0 +1,155 @@
+# 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
+
+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
+    DATABASE_PATH=data/users.db
+    ```
+
+    Note: The `DATABASE_PATH` uses a relative path. For persistence and consistency, it's recommended to use an absolute path or ensure the volume mount covers this path if using Docker. The `utils/database.py` script will attempt to create the directory `data` if it doesn't exist relative to where the script is run.
+
+### 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`, `DATABASE_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 user-service \
+      -p 8000:8000 \
+      -v user-service-data:/data \
+      -e SUPER_ADMIN_USER=your_super_admin_username \
+      -e SUPER_ADMIN_PASSWORD=your_super_admin_password \
+      user-registration-service
+    ```
+
+    Replace `your_super_admin_username` and `your_super_admin_password` with your desired credentials. The `-v user-service-data:/data` maps a Docker volume for persistent storage of the SQLite database defined by `DATABASE_PATH=/data/users.db` in the Dockerfile.
+
+    The application will be available at `http://localhost:8000` (or your Docker host's IP).
+
+## 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).*