juansecu/openfusion-openapi-plugin repository overview

OpenAPI definition plugin for server applications based on OpenFusion⁠.

⁠Requirements

• Database - An existent SQLite database of OpenFusion⁠

• SMTP (Simple Mail Transfer Protocol) Server that supports MIME messages and TLS connections

• Environment variables

  Variable	Type	Description	Required	Default	Example
  CORS_ALLOWED_ORIGINS	String	The origins that are allowed to access the application, separated by ,	Yes	None	http://localhost:3000,https://example.com
  DATABASE_PATH	String	The path to the OpenFusion database to connect	Yes	None	C:\Users\user\Desktop\OpenFusion\database.db
  ISSUER_NAME	String	The name of the entity that will provide JSON Web Tokens and send emails	Yes	None	Great Fusion
  JWT_SECRET	String	The secret to sign/verify JSON Web Tokens	Yes	None	<JSON Web Token Secret>
  MAIL_SERVER_FROM_ACCOUNT_RELATED_EMAIL_ADDRESS	String	The e-mail address that will be used to send e-mails related to account management	Yes	None	[email protected]
  MAIL_SERVER_HOST	String	The host address where the SMTP server is running on	No	smtp.gmail.com	smtp.gmail.com
  MAIL_SERVER_PASSWORD	String	The password of the user who will send e-mails	Yes	None	<mail server password>
  MAIL_SERVER_PORT	Integer	The port where the SMTP server is running on	No	587	587
  MAIL_SERVER_USERNAME	String	The user who will be used to sign into the SMTP server	Yes	None	[email protected]
  PORT	Integer	The port where the application will run on	No	8080	80
  PUBLIC_ADDRESS	String	The public address where clients and browsers will be able to access the application from	No	http://localhost:8080	https://example.com
  VERIFICATION_TOKEN_SALT_KEY	String	The salt key to encrypt and decrypt verification tokens	Yes	None	<verification token salt key>
  VERIFICATION_TOKEN_SECURITY_KEY	String	The key to encrypt and decrypt verification tokens	Yes	None	<verification token security key>

  
  

  Notes:

  • All required environment variables must be set before running the application.
  • Never give environment variable values to non-administrator users, since they could hack your server instance.
  • You can generate secrets using tools like Random Key Gen⁠. 256-bit keys are recommended.
  • For setting the PUBLIC_ADDRESS environment variable, you can use your domain name or your public IP address.
  • For security reasons, it is recommended to use a dedicated e-mail account to send e-mails.
  • For security reasons, VERIFICATION_TOKEN_SALT_KEY and VERIFICATION_TOKEN_SECURITY_KEY must be different from each other.
  • For setting up the MAIL_SERVER_* environment variables, check out the SMTP Server⁠ setup section.

⁠Configuration

⁠SSL Configuration

To enable SSL, you can use any of the following methods:

• Java KeyStore file⁠.
• PEM files⁠.
• SSL Bundle⁠

Once you have chosen a method to enable SSL, you can pass the necessary JVM arguments to the application by passing each argument following the -D flag when running the application.

Note that you can also use a reverse proxy (e.g. Nginx, Apache, etc.).

⁠Features

You can check the current state of features here⁠.

⁠API Documentation

The API documentation is available at the endpoint /docs. Keep in mind that the API documentation is only available for users with any of the following levels of permissions:

• DEVELOPER (Level 50)
• GAME MASTER (Level 30)
• MASTER (Level 1)

⁠User Interface

The user interface is available at the endpoint /auth/login.

⁠Running

For running the application with Docker, you will need to mount the database file using Docker volumes and map port 8080 to your host machine.

⁠Docker CLI

• Windows

  # For running the application without SSL
  > docker run -dp 8080:8080 \
      -v <path\to\database>:${DATABASE_PATH} \
      --env-file <path\to\env\file> \
      --name <container-name> \
      juansecu/openfusion-openapi-plugin:v<version number>
  
  # For running the application with SSL
  > docker run -dp 8080:8080 \
      -v <path\to\database>:${DATABASE_PATH} \
      <additional volumes for SSL certificates> \
      --env-file <path\to\env\file> \
      --name <container-name> \
      --entrypoint "java <JVM arguments> -jar /app/app.jar" \
      juansecu/openfusion-openapi-plugin:v<version number>
  

  Copy

• MacOS/Linux

  # For running the application without SSL
  $ docker run -dp 8080:8080 \
      -v <path/to/database>:${DATABASE_PATH} \
      --env-file <path/to/env/file> \
      --name <container-name> \
      juansecu/openfusion-openapi-plugin:v<version number>
  
  # For running the application with SSL
  $ docker run -dp 8080:8080 \
      -v <path/to/database>:${DATABASE_PATH} \
      <additional volumes for SSL certificates> \
      --env-file <path/to/env/file> \
      --name <container-name> \
      --entrypoint "java <JVM arguments> -jar /app/app.jar" \
      juansecu/openfusion-openapi-plugin:v<version number>
  

  Copy

⁠Docker Compose

For running the application with Docker Compose, you can use the Docker Compose file⁠ provided in this repository for development and production, but for production, you will also need to remove the build property from the openapi service, change the image property to juansecu/openfusion-openapi-plugin:v<version number> and configure the following environment variables:

• LOCAL_DATABASE_PATH - The path in the host machine to the OpenFusion database to connect

⁠Adding SSL

For running the application with SSL, you will need to set the necessary JVM arguments in the command property of the openapi service, and mount the SSL certificate files using Docker volumes.

# Windows
services:
  openapi:
    ...
    volumes:
      - <path\to\database>:/app/database
      # Additional volumes for SSL certificates...
    command: java <JVM arguments> -jar /app/app.jar

# MacOS/Linux
services:
  openapi:
    ...
    volumes:
      - <path/to/database>:/app/database
      # Additional volumes for SSL certificates...
    command: java <JVM arguments> -jar /app/app.jar

After configuring the environment variables, you can run the application using the following command:

$ docker compose up -d