OpenBMCLAPI Documentation

OpenBMCLAPI is a project designed to assist BMCLAPI in distributing Minecraft resources. It helps mitigate slow download speeds for Forge and official Minecraft resources (hosted on Amazon S3) for users on domestic (Chinese) networks.

To participate as a node, your environment should meet these requirements:

• Publicly accessible (port mapping is allowed, non-80 ports are fine).
• Upload speed of at least 10Mbps.
• Stable online presence.
• Does not currently support IPv6-only nodes (dual-stack is supported).
• Currently, international nodes are not being accepted.

To use Docker Compose, first create a .env file or modify the docker-compose.yml file based on the required configuration parameters. Then, run the following command to start the service in detached mode:

docker compose up -d

OpenBMCLAPI automatically synchronizes required files, but initial synchronization may be slow. If you are running a full node, you can use rsync to speed up the process. You can use any of the following rsync servers:

• rsync -rzvP openbmclapi@home.933.moe::openbmclapi cache
• rsync -avP openbmclapi@storage.yserver.ink::bmcl cache
• rsync -azvrhP openbmclapi@openbmclapi.home.mxd.moe::data cache

You can run OpenBMCLAPI as a Docker container. Ensure you provide the required CLUSTER_ID, CLUSTER_SECRET, and CLUSTER_PUBLIC_PORT environment variables.

If you cannot access Docker Hub, use the domestic mirror: docker pull registry.bangbang93.com/bmclapi/openbmclapi

docker run -d \
-e CLUSTER_ID=${CLUSTER_ID} \
-e CLUSTER_SECRET=${CLUSTER_SECRET} \
-e CLUSTER_PUBLIC_PORT=${CLUSTER_PORT} \
-e TZ=Asia/Shanghai \
-v /data/openbmclapi:/opt/openbmclapi/cache \
-p ${CLUSTER_PORT}:4000 \
--restart always \
--name openbmclapi \
bangbang93/openbmclapi

To install from source, you need Node.js 18 or higher. The process works on Windows, MacOS, Linux, x86, and ARM architectures.

1. Install Node.js LTS from nodejs.org.
2. Clone the repository and install dependencies, build, and run:

git clone https://github.com/bangbang93/openbmclapi
cd openbmclapi
npm ci
npm run build
node dist/index.js

If you see the error CLUSTER_ID is not set, the installation was successful and you now need to configure the parameters.

For source installations, create a .env file in the project root directory and define your cluster credentials and port. You must contact the maintainer to obtain your CLUSTER_ID and CLUSTER_SECRET.

CLUSTER_ID=你的CLUSTER_ID
CLUSTER_SECRET=你的CLUSTER_SECRET
CLUSTER_PORT=对外访问端口

When running in daemon mode (the default), the application uses Node.js cluster to manage worker processes.

• Automatic Restarts: If a worker process exits unexpectedly, the primary process implements an exponential backoff strategy to restart it. The backoff factor is 2, with a maximum delay of 60 seconds, and includes a randomization factor (±20%) to prevent thundering herd issues.
• Ready State: The backoff timer is reset to 1 second once a worker sends a 'ready' message to the primary process.
• Graceful Shutdown: Upon receiving SIGINT or SIGTERM, the primary process attempts to kill the worker and waits up to 30 seconds for a clean exit before forcing the process to terminate.

The Cluster class is the central component for managing node coordination, file synchronization, and server lifecycle in OpenBMCLAPI. It handles communication with the central server via Socket.io, manages local storage, and can orchestrate an Nginx reverse proxy for serving files.

Key responsibilities include:

• Node Registration: Enabling/disabling the node on the central server.
• File Syncing: Fetching file lists and synchronizing missing files from the central server.
• Server Management: Setting up Express/HTTP2 servers or Nginx configurations.
• Certificate Management: Requesting or using local SSL certificates.

import { Cluster } from './cluster.js';

// Example instantiation (internal usage pattern)
const cluster = new Cluster(clusterSecret, version, tokenManager);

By default, OpenBMCLAPI runs in a clustered mode where a primary process manages worker processes. If you want to run the application in a single process without the daemon/cluster management, set the NO_DAEMON environment variable to true. This is useful for debugging or running in environments where process management is handled externally.

export NO_DAEMON=true

You can deploy OpenBMCLAPI using Docker Compose. The service uses the bangbang93/openbmclapi image and exposes port 4000.

To ensure proper connectivity and security, you must provide CLUSTER_ID and CLUSTER_SECRET via environment variables. The service also supports a persistent cache directory mapped to ./cache in your local directory.

version: '3'
services:
  openbmclapi:
    image: bangbang93/openbmclapi
    environment:
      CLUSTER_ID: ${CLUSTER_ID}
      CLUSTER_SECRET: ${CLUSTER_SECRET}
      CLUSTER_PUBLIC_PORT: 4000
      TZ: Asia/Shanghai
    volumes:
    - ./cache:/opt/openbmclapi/cache
    ports:
    - "4000:4000"
    restart: always