135 lines
3.9 KiB
Markdown
135 lines
3.9 KiB
Markdown
# Hangman Lab Frontend
|
|
|
|
This project serves as a lightweight frontend solution for personal websites, designed to work seamlessly with Keycloak for authentication and authorization. It provides an easy-to-use interface for managing and publishing markdown files, allowing users to maintain their personal content effortlessly.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Technologies Used](#technologies-used)
|
|
- [Installation](#installation)
|
|
- [Configuration](#configuration)
|
|
- [Development](#development)
|
|
- [Building for Production](#building-for-production)
|
|
- [Docker Deployment](#docker-deployment)
|
|
- [License](#license)
|
|
|
|
## Features
|
|
|
|
- **User Authentication**: Secure login and logout functionalities using **Keycloak** and **OpenID Connect (OIDC)**.
|
|
- **Markdown Management**: Create, edit, and view markdown files with live preview and syntax highlighting for a streamlined content creation experience.
|
|
- **Docker Support**: Containerized setup for easy deployment and scalability.
|
|
|
|
|
|
## Technologies Used
|
|
|
|
This project uses the following open-source libraries, all of which are licensed under the MIT License:
|
|
|
|
- [Bulma](https://bulma.io/) (MIT)
|
|
- [Katex](https://katex.org/) (MIT)
|
|
- [oidc-client-ts](https://github.com/authts/oidc-client-ts) (Apache-2.0)
|
|
- [React](https://reactjs.org/) (MIT)
|
|
- [React-DOM](https://reactjs.org/) (MIT)
|
|
- [React-Markdown](https://github.com/remarkjs/react-markdown) (MIT)
|
|
- [React-Query](https://react-query-v3.tanstack.com/) (MIT)
|
|
- [React-Router-DOM](https://reactrouter.com/) (MIT)
|
|
- [React-Syntax-Highlighter](https://github.com/react-syntax-highlighter/react-syntax-highlighter) (MIT)
|
|
- [Rehype-Katex](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex) (MIT)
|
|
- [Rehype-Raw](https://github.com/rehypejs/rehype-raw) (MIT)
|
|
- [Remark-Math](https://github.com/remarkjs/remark-math) (MIT)
|
|
|
|
The development dependencies (e.g., Babel, Webpack, and loaders) are also licensed under the MIT License.
|
|
|
|
## Installation
|
|
### Prerequisites
|
|
- **Node.js** (v14.x or higher)
|
|
- **npm** (v6.x or higher) or **Yarn**
|
|
- **Docker** (optional, for containerized deployment)
|
|
- **Keycloak Server**: Ensure you have access to a Keycloak server for authentication.
|
|
|
|
### Steps
|
|
|
|
1. **Clone the Repository**
|
|
|
|
```bash
|
|
git clone https://git.hangman-lab.top/hzhang/HangmanLab.Frontend.git
|
|
cd HangmanLab.Frontend
|
|
```
|
|
|
|
2. **Install Dependencies**
|
|
|
|
Using npm:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
Or using Yarn:
|
|
|
|
```bash
|
|
yarn install
|
|
```
|
|
|
|
3. **Configure environment variables**
|
|
|
|
See Configuration[#configuration]
|
|
|
|
4. **BuildConfig.sh**
|
|
|
|
```bash
|
|
chmod +x BuildConfig
|
|
./BuildConfig.sh
|
|
```
|
|
|
|
## Configuration
|
|
Set the following environment variables before running BuildConfig.sh
|
|
|
|
### Environment Variables
|
|
- `BACKEND_HOST`: URL of the backend server (default: `http://localhost:5000`)
|
|
- `FRONTEND_HOST`: URL of the frontend server (default: `http://localhost:3000`)
|
|
- `KC_CLIENT_ID`: Keycloak client ID
|
|
- `KC_HOST`: Keycloak server URL
|
|
- `KC_REALM`: Keycloak realm
|
|
|
|
|
|
## Development
|
|
|
|
### Running the Development Server
|
|
|
|
Start the development server with hot reloading:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Or using Yarn:
|
|
|
|
```bash
|
|
yarn start
|
|
```
|
|
|
|
The application will be accessible at `http://localhost:3000` by default.
|
|
|
|
|
|
## Docker Deployment
|
|
|
|
### Image
|
|
Pull the latest Docker image from the registry:
|
|
```bash
|
|
docker pull git.hangman-lab.top/hzhang/hangmanlab-frontend:latest
|
|
```
|
|
|
|
### Running the Docker Container
|
|
Ensure your backend service (e.g., running at http://localhost:5000) is up and accessible. Then, run the Docker container:
|
|
```bash
|
|
docker run -d -p 80:80 --name hangmanlab-frontend hangmanlab-frontend:latest
|
|
```
|
|
|
|
#### Note:
|
|
- The container listens on port 80. Adjust the port mapping (-p) as needed.
|
|
- Make sure to set the appropriate environment variables either in the Dockerfile or via Docker environment variable options.
|
|
## License
|
|
[MIT][license] © [hzhang][author]
|
|
|
|
<!-- Definitions -->
|
|
[author]: https://hangman-lab.top
|
|
[license]: license |