app readme.md

README.md

@@ -1,3 +1,100 @@
-```bash
+# Random Word API
-uv run uvicorn main:app --reload
+
+A lightweight, Dockerized REST API built with [FastAPI](https://fastapi.tiangolo.com/) that serves random words. Ideal for games like Hangman, Pictionary, or typing practice apps.
+
+## 🌐 Live Demo
+
+You can test the API live at: [https://random.out.jafre.li/random_word](https://random.out.jafre.li/random_word)
+
+## 🚀 Features
+
+- **Random Word Generation**: Efficiently retrieves a random word from a SQLite database.
+- **Fast & Lightweight**: Built on Python 3.12 and FastAPI.
+- **Docker Ready**: Includes a production-ready `Dockerfile` with `uv` for fast builds.
+- **Persistent Storage**: Configurable database path for data persistence.
+
+## 🛠️ Tech Stack
+
+- **Framework**: FastAPI
+- **Database**: SQLite
+- **Server**: Uvicorn / Gunicorn
+- **Package Manager**: uv
+- **Containerization**: Docker
+
+## 🔌 API Endpoints
+
+### `GET /random_word`
+
+Returns a single random word from the database.
+
+**Response:**
+```json
+{
+  "word": "Schmetterling"
+}
 ```
+
+**Error Response:**
+```json
+{
+  "error": "Keine Wörter in hangman.db gefunden."
+}
+```
+
+## 🏁 Getting Started
+
+### Local Development
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://git.out.jafre.li/jafreli/Random-Word-API.git
+    cd Random-Word-API
+    ```
+
+2.  **Install dependencies:**
+    This project uses `uv` for package management, but standard `pip` works too.
+    ```bash
+    pip install -r pyproject.toml
+    # OR if you have uv installed:
+    uv pip install -r pyproject.toml
+    ```
+
+3.  **Initialize the database:**
+    Run the initialization script to create `hangman.db` and populate it with the default word list.
+    ```bash
+    python init.py
+    ```
+
+4.  **Start the server:**
+    ```bash
+    fastapi dev main.py
+    # OR using uvicorn directly:
+    uvicorn main:app --reload
+    ```
+    The API will be available at `http://localhost:8000/random_word`.
+
+### 🐳 Docker Usage
+
+1.  **Build the image:**
+    ```bash
+    docker build -t random-word-api .
+    ```
+
+2.  **Run the container:**
+    Mount a volume to `/app/data` to persist the database.
+    ```bash
+    docker run -d -p 8080:80 -v $(pwd)/data:/app/data random-word-api
+    ```
+
+    *Note: The container is configured to look for the database at `/app/data/hangman.db` by default.*
+
+3.  **Access the API:**
+    Go to `http://localhost:8080/random_word`.
+
+## ⚙️ Configuration
+
+You can configure the application using environment variables:
+
+| Variable  | Description | Default |
+| :--- | :--- | :--- |
+| `DB_PATH` | Path to the SQLite database file. | `hangman.db` (Local) / `/app/data/hangman.db` (Docker) |