cloud-core-server

An open-source way to run Minecraft easily on linux using JavaScript.

Usage no npm install needed!

<script type="module">
  import cloudCoreServer from 'https://cdn.skypack.dev/cloud-core-server';
</script>

README

An open-source way to run Minecraft easily on linux using Express & Websockets.

CodeFactor Maintainability npm bundle size npm

Cloud Core is a highly configurable Minecraft Java wrapper, it uses child_process, express, websocket and many other modules to expose your Minecraft Java server to the web.

  • HTTP Api for sending commands, requesting the last 100 lines of console and getting the server usage statistics (cpu & ram).
  • Websocket support to receive console lines, send commands and start / stop the server.
  • A fully automated backup system that backs up your whole server on a bi-weekly / bi-monthly basis.
  • Highly customizable with events, and functions to interact with the server from plain javascript.
  • Highly secured, only letting users with a certain password connect.
  • Logs every command sent into the Minecraft latest log with an optional user field to log a command by a user.

Install

Firstly make sure you have the following dependencies:

  • Java 8 or above.
  • NodeJS 12 or above.
  • Access to SSH on your host.

Install via NPM...

npm install cloud-core-server

To start a server, you need to create a javascript file in the root of your server.

Include Cloud Core into this script by entering this line:

const CloudCore = require("cloud-core-server");

Then make a new instance of CloudCore:

const server = new CloudCore(options);

You need to configure most of the options, download the example-start.js file to see an example of what you might find, all options and default values are listed here:

core:

Option About Default Value
path Path to minecraft server where the .jar file is located. "./"
prefix Path to add at the start of the java command, this is useful for switching java version for specified servers. E.g. "/usr/lib/jvm/jdk-16.0.1/bin/" to use java 16. MAKE SURE STRING ENDS WITH / ""
jar Main java file for the server. "server.jar"
authorization Main authorization code for any request. "hackme"
args Array of java flags, including ram and other options. (Minecraft Jar Flags) ['-Xmx2G', '-Xms1G']
port Minecraft server port. 25565

core.backups:

Option About Default Value
enabled Do you want automatic backups? false
time How much time do you want per backup? Can be only "weekly" OR "monthly" "weekly"
directory Where do you want to save any backups? "./backup/"

remote:

Option About Default Value
bind IP Address to bind the webserver to. "0.0.0.0"
port Port to bind the webserver to. 35565

Running

Start your server by installing pm2 and running this command:

pm2 start (your start javascript file) -n (server name)

Your server will now be started. You can use pm2 log (server name) to view the server log or if there are any errors.

Be careful when you are stopping your server. If you stop your server via pm2 stop (server name) your server can be shut down incorrectly. Please first stop your server through the web, then stop it via pm2.

You can also start multiple servers using pm2.

Accessing

HTTP GET request to any URL to get the last 100 lines of the console.

HTTP POST request to any URL to send a command.

Open websocket to any URL.

Start & stop.

Make sure you follow authentication rules.

Also have a look at proxying your webserver to ensure security.

Getting CPU & RAM Usage.

Get console

$context = [
  "http" => [
      "method" => "GET",
      "header" => "Authorization: <auth code here>"
  ]
];

$console = file_get_contents("http://localhost:35565/", false, stream_context_create($context))

Post command

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,"http://localhost:35565/");
curl_setopt($ch, CURLOPT_POST, 1);
$authHeaders = array(
  "Authorization: <auth code here>",
  "Content-type: application/json"
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $authHeaders);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array("command" => "command here", "user" => "optional user here")));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server_output = curl_exec($ch);

curl_close ($ch);

Websocket

webSocket = new WebSocket('ws://localhost:35565', 'auth code here');
webSocket.onmessage = (message) => {
    let line = message.data;
    console.log(line)
};

webSocket.send(JSON.stringify({"action": "command", "command": "command here", "user": "optional user here"}))

Important Note: You must have a ping/pong event every ~10 seconds to keep the websocket connection alive. To do this put ping for the action field. The server will return a pong in raw text. I advise you to have an if statement to make sure you filter it out.

Starting & Stopping

In the websocket, specify the action field as either: start, stop, restart or kill.

In HTTP, specify the command field as either start, stop or restart.

Note: You can still pass the user field.

Authentication

All requests include a Authorization header with the auth code you set in the start.js file.

Pass the authentication code in the protocall for websockets. See Above

Proxying the Server

It is highly recommended that you proxy your webserver as this does not support https at the moment. Here are some articles on how you can do that.

Setting up NGINX as your proxy server with NodeJS apps

How to Setup Apache As Frontend Proxy for Node.js

Usage HTTP API

Make a GET request to /usage to return a json array of the server's current CPU load and ram.

$context = [
  "http" => [
      "method" => "GET",
      "header" => "Authorization: <auth code here>"
  ]
];

$usage = file_get_contents("http://localhost:35565/usage", false, stream_context_create($context))
$usage = json_decode($usage, true);

API

Events

Methods

Events

Register an event by doing:

server.on("event name", (params) => {
  // do stuff
})
Event Name Description Parameters
ready Ready to start server.
command When a command is executed from either the web or websocket. command
console When the server returns a console line. NOTE: If you emit this event, it will return whatever text you pass to the websocket. line
start When the server is started.
started When the server has finshed starting.
stopping When server tries to stop.
stop When server fully stops.
backup When server is backed up, includes filepath to zip file. path

Methods

Method Name Description Parameters
server.start() Starts server.
server.stop() Tries to stop server and executes callback when fully stopped. Callback Function
server.send() Sends a command to the server. Command to send
server.backup() Backs up the server reguardless of having backups enabled.
server.wsServer Access websocket server Websocket Module.
server.httpServer Returns running express server
server.minecraftServer Returns child process spawn running the server. (Advanced Users Only)

Help

To get help feel free to message me on discord Chezzer#6969.