improve: fix README
This commit is contained in:
187
README.md
Normal file
187
README.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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](#features)
|
||||
- [Requirements](#requirements)
|
||||
- [Installation](#installation)
|
||||
- [Configuration](#configuration)
|
||||
- [Docker Deployment](#docker-deployment)
|
||||
- [Usage](#usage)
|
||||
- [API Endpoints](#api-endpoints)
|
||||
- [Database Models](#database-models)
|
||||
- [Logging](#logging)
|
||||
- [License](#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
|
||||
|
||||
```bash
|
||||
git clone https://git.hangman-lab.top/hzhang/HangmanLab.Backend.git
|
||||
cd hangmanlab-backend
|
||||
```
|
||||
|
||||
### 2. Install dependencies
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
docker pull git.hangman-lab.top/hzhang/hangmanlab-backend:latest
|
||||
```
|
||||
|
||||
### Running the Docker Container
|
||||
|
||||
```bash
|
||||
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][license] © [hzhang][author]
|
||||
|
||||
<!-- Definitions -->
|
||||
[author]: https://hangman-lab.top
|
||||
[license]: license
|
||||
Reference in New Issue
Block a user