HangmanLab.Frontend/README.md

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
• Technologies Used
• Installation
• Configuration
• Development
• Building for Production
• Docker Deployment
• 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 (MIT)
• Katex (MIT)
• oidc-client-ts (Apache-2.0)
• React (MIT)
• React-DOM (MIT)
• React-Markdown (MIT)
• React-Query (MIT)
• React-Router-DOM (MIT)
• React-Syntax-Highlighter (MIT)
• Rehype-Katex (MIT)
• Rehype-Raw (MIT)
• 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

   git clone https://git.hangman-lab.top/hzhang/HangmanLab.Frontend.git
   cd HangmanLab.Frontend
   

2. Install Dependencies

   Using npm:

   npm install
   

   Or using Yarn:

   yarn install
   

3. Configure environment variables

   See Configuration[#configuration]

4. BuildConfig.sh

   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:

npm start

Or using Yarn:

yarn start

The application will be accessible at http://localhost:3000 by default.

Docker Deployment

Image

Pull the latest Docker image from the repository:

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

Building the docker Image

docker build -t hangman-lab-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:

docker run -d -p 80:80 --name hangman-lab-frontend hangman-lab-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 © hzhang