An open-source way to run Minecraft easily on linux using Express & Websockets.
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.
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 |
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.
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.
Make sure you follow authentication rules.
Also have a look at proxying your webserver to ensure security.
$context = [
"http" => [
"method" => "GET",
"header" => "Authorization: <auth code here>"
]
];
$console = file_get_contents("http://localhost:35565/", false, stream_context_create($context))
$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 = 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.
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.
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
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
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);
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 |
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) |
To get help feel free to message me on discord Chezzer#6969
.