HangmanLab.Backend/README.md

HangmanLab Backend

This project provides the backend infrastructure for the HangmanLab application. It is built using Flask, SQLAlchemy, and other supporting libraries.

---

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Docker Deployment
• Usage
• API Endpoints
• Database Models
• Logging
• License

---

Features

• Authentication: JWT-based authentication integrated with Keycloak.
• Rate Limiting: Protects endpoints using Flask-Limiter.
• CRUD Operations: Manage paths, markdown files, resources, and logs.
• Database Support: Uses MySQL with SQLAlchemy ORM.
• ETag Support: Optimized response caching with ETags.
• Modular Design: Easy-to-extend and maintain.

---

Requirements

• Python 3.9 or higher
• MySQL 8.0 or higher
• Keycloak for authentication
• Node.js (optional, for frontend integration)

---

Installation

1. Clone the repository

git clone https://git.hangman-lab.top/hzhang/HangmanLab.Backend.git
cd hangmanlab-backend

2. Install dependencies

pip install -r requirements.txt

3. Set up the database

Ensure you have a MySQL instance running. Update the .env file with the database credentials.

cp .env.example .env

Edit the .env file to configure your environment variables.

4. Initialize the database

Configuration

The application uses environment variables to manage configuration. These variables are set in the .env file. Key variables include:

• Database Configuration:
  • DB_HOST
  • DB_PORT
  • DB_NAME
  • DB_USER
  • DB_PASSWORD
• Keycloak Configuration:
  • KC_HOST
  • KC_REALM
  • KC_CLIENT_ID
• Other Settings:
  • SESSION_SECRET_KEY
  • FRONTEND_HOST

---

Usage

Running the Application

Run the following command to start the Flask server:

python app.py

The server will start on http://0.0.0.0:5000.

Accessing the API

All endpoints are prefixed with /api (e.g., /api/path, /api/log).

---

Docker Deployment

Image

Pull the latest Docker image from the registry

docker pull git.hangman-lab.top/hzhang/hangmanlab-backend:latest

Running the Docker Container

docker run -d -p 80:80 --name hangmanlab-backend hangmanlab-backend:latest

---

API Endpoints

Path Management

• GET /api/path/: Retrieve root paths.
• GET /api/path/<int:path_id>: Retrieve a specific path.
• POST /api/path/: Create a new path.
• PUT/PATCH /api/path/<int:path_id>: Update an existing path.
• DELETE /api/path/<int:path_id>: Delete a path.

Markdown Management

• GET /api/markdown/: Retrieve all markdown files.
• GET /api/markdown/by_path/<int:path_id>: Retrieve markdowns by path.
• POST /api/markdown/: Create a new markdown file.
• PUT/PATCH /api/markdown/<int:markdown_id>: Update an existing markdown file.
• DELETE /api/markdown/<int:markdown_id>: Delete a markdown file.

Resource Management

• GET /api/resource/<identifier>: Retrieve a resource.
• POST /api/resource/: Create a new resource.
• DELETE /api/resource/<identifier>: Delete a resource.

Logging

• GET /api/log/: Retrieve logs with filtering options.
• POST /api/log/: Create a new log entry.

Configuration Management

• GET /api/config/limits: Retrieve current rate limits.
• PUT /api/config/limits: Update rate limits.

---

Database Models

Key Models

1. Path: Represents a file system path.
2. Markdown: Represents markdown files associated with paths.
3. Resource: Binary resources (e.g., images, documents).
4. Log: Application logs for auditing and debugging.

---

Logging

The project uses a custom DatabaseLogHandler to log messages directly to the database. Logs include the following details:

• Level (e.g., INFO, ERROR)
• Message
• Timestamp
• Application name

---

License

MIT © hzhang