Gml.Web.Api

Gml.Web.Api is a RESTful web service within the Gml microservices ecosystem, providing APIs for server-side operations, managing game accounts, and profiles for Minecraft (supporting Vanilla, Forge, NeoForge, Fabric, and LiteLoader, Quilt). This README explains how to set up and run the service, which uses SQLite as its database and relies on environment variables for configuration.

Prerequisites

Ensure the following are installed:

• .NET 10.0 SDK: Install from Microsoft's official website.
• Git: Install from Git website or via your package manager.
• Docker (optional, for containerized deployment): Install Docker Desktop from Docker's official website.
• A code editor like Visual Studio or Visual Studio Code (optional, for development).

Installation and Setup

Follow these steps to clone, configure, and run the Gml.Web.Api project.

1. Clone the Repository

Clone the repository using Git:

git clone --recursive https://github.com/Gml-Launcher/Gml.Web.Api.git
cd Gml.Web.Api

2. Restore Dependencies

Restore .NET project dependencies:

dotnet restore

3. Configure Environment Variables

The service is configured using environment variables, which control the SQLite database, security settings, project details, and service endpoints. Set these variables before running the application. You can set them in your shell, a .env file (if supported by your setup), or pass them to Docker.

Required environment variables:

• ASPNETCORE_ENVIRONMENT: Environment mode (e.g., Development for local testing, Production for deployment).
• SECURITY_KEY: A secure key for authentication/encryption (e.g., <your-security-key>). Use a strong, unique key.
• PROJECT_NAME: Name of the project (e.g., GmlServer).
• PROJECT_DESCRIPTION: Description of the project (e.g., GmlServer Description).
• PROJECT_POLICYNAME: Policy name for authorization (e.g., GmlPolicy).
• PROJECT_PATH: Base path for the project (leave empty "" unless specified otherwise).
• SERVICE_TEXTURE_ENDPOINT: URL for the texture service endpoint (e.g., http://localhost:5086).
• AllowedHosts: Allowed hosts for the API (e.g., * to allow all).

In Development, if SECURITY_KEY is not set, the API generates a random key on its first launch and stores it in src/Gml.Web.Api/database/development.key. Subsequent launches reuse that key. The file is excluded from Git, and an explicitly set environment variable takes precedence. Production requires SECURITY_KEY in the environment.

Example (Linux/macOS):

ASPNETCORE_ENVIRONMENT="Development"
SECURITY_KEY="<your-security-key>"
PROJECT_NAME="GmlServer"
PROJECT_DESCRIPTION="GmlServer Description"
PROJECT_POLICYNAME="GmlPolicy"
PROJECT_PATH=""
SERVICE_TEXTURE_ENDPOINT="http://localhost:5086"
AllowedHosts="*"

On Windows, use set in Command Prompt:

set ASPNETCORE_ENVIRONMENT=Development
set SECURITY_KEY=<your-security-key>
set PROJECT_NAME=GmlServer
set PROJECT_DESCRIPTION=GmlServer Description
set PROJECT_POLICYNAME=GmlPolicy
set PROJECT_PATH=
set SERVICE_TEXTURE_ENDPOINT=http://localhost:5086
set AllowedHosts=*

Note: The SQLite database path is managed internally by the application. Ensure the directory where the database file will be created is writable.

4. Build the Project

Build the project to check for errors:

dotnet build

6. Run the Application

Run the service locally:

dotnet run --project src/Gml.Web.Api/Gml.Web.Api.csproj

The API will be available at https://localhost:5001 or http://localhost:5000 (check terminal output for the port). Test the API with tools like Postman or curl:

curl http://localhost:5000/api/profiles

5. (Optional) Run with Docker

To run the service in a Docker container:

1. Build the Docker image:

docker build -t gml-web-api .

To embed the source version and commit, pass build arguments from this repository:

docker build -t gml-web-api \
  --build-arg BUILD_VERSION="$(git describe --tags --exact-match 2>/dev/null || git branch --show-current)" \
  --build-arg BUILD_COMMIT="$(git rev-parse HEAD)" .

BUILD_VERSION is the full release tag (including v) or the branch name, and BUILD_COMMIT is the full SHA of the checked-out backend commit. GitHub Actions supplies these automatically for both image architectures. Pull request builds use the source branch name and the SHA of the checkout actually built (normally the PR merge commit). Builds without arguments use development and unknown.

These values are stored in the published .NET assembly and cannot be changed by runtime environment variables. For a build without Docker, pass -p:BuildVersion=... -p:BuildCommit=... to dotnet publish.

Panel users can read the embedded values with GET /api/v1/system/version, using Authorization: Bearer <access-token>. The response follows the usual ResponseMessage format, with data: { "version": "v2026.1-beta1", "commit": "<full-commit-sha>" }, and Cache-Control: no-store. Any authenticated panel user can access it, without an Admin role or additional permissions. Missing, invalid or expired JWTs and external application API keys receive 401 Unauthorized.

2. Run the container, passing environment variables:

docker run -d -p 5000:80 --name gml-web-api \
  -e "ASPNETCORE_ENVIRONMENT=Development" \
  -e "SECURITY_KEY=<your-security-key>" \
  -e "PROJECT_NAME=GmlServer" \
  -e "PROJECT_DESCRIPTION=GmlServer Description" \
  -e "PROJECT_POLICYNAME=GmlPolicy" \
  -e "PROJECT_PATH=" \
  -e "SERVICE_TEXTURE_ENDPOINT=http://localhost:5086" \
  -e "AllowedHosts=*" \
  gml-web-api

The API will be accessible at http://localhost:5000. The SQLite database file will be created inside the container. To persist the database, mount a volume:

docker run -d -p 5000:80 --name gml-web-api \
  -v /path/to/local/db:/app \
  -e "ASPNETCORE_ENVIRONMENT=Development" \
  -e "SECURITY_KEY=<your-security-key>" \
  -e "PROJECT_NAME=GmlServer" \
  -e "PROJECT_DESCRIPTION=GmlServer Description" \
  -e "PROJECT_POLICYNAME=GmlPolicy" \
  -e "PROJECT_PATH=" \
  -e "SERVICE_TEXTURE_ENDPOINT=http://localhost:5086" \
  -e "AllowedHosts=*" \
  gml-web-api

Replace /path/to/local/db with a local directory to store the SQLite database file.

Troubleshooting

• Database Access Issues: Ensure the SQLite database file directory is writable.
• Port Conflicts: If port 5000/5001 is in use, set ASPNETCORE_URLS (e.g., ASPNETCORE_URLS=http://localhost:8080).
• Dependency Errors: Confirm .NET 8.0 SDK is installed and run dotnet restore.
• Docker Issues: Check container logs with docker logs gml-web-api to diagnose errors. Ensure the SQLite database path is accessible.

Additional Notes

• For production, configure HTTPS and use a reverse proxy (e.g., Nginx).
• Monitor the API using the Gml.Web.Client dashboard from the Gml.Backend repository.
• Visit the Gml-Launcher organization or open an issue in this repository for support.