Skip to content

Clusterio

Clusterio is a clustered Factorio server manager that provides the tooling for implementing cross server interactions in Factorio. It was previously best known for implementing cross server transfer and cloud storage of items via teleporter chests. But this functionality has been pulled out of Clusterio into its own plugin for Clusterio named Subspace Storage. By itself Clusterio doesn't change the gameplay in any way, you could even use Clusterio to manage completely vanilla Factorio servers. Plugins do the work of modding in the visible changes into the game, see the Plugins section for ready-made plugins you can install into a Clusterio cluster.

egg-clusterio.json

updated

Ports
8081, 34197
Runtime
Node.js 18 to 21
Variables
8

Ports

Add an allocation on the node for each port.

  • Controller HTTP 8081
  • Host Game 34197

Install

Installer image
node:21-bookworm-slim
Install script
31 lines

Images

New servers use the first image. Users can change it on the Startup page.

  • NodeJS 21 default ghcr.io/ptero-eggs/yolks:nodejs_21
  • NodeJS 20 ghcr.io/ptero-eggs/yolks:nodejs_20
  • NodeJS 19 ghcr.io/ptero-eggs/yolks:nodejs_19
  • NodeJS 18 ghcr.io/ptero-eggs/yolks:nodejs_18

Startup

The Panel runs this command to start the server. It replaces each variable in the command with the value of that variable.

8 variables

Startup command

exec ./node_modules/.bin/clusteriocontroller run

  • Set's the cluster operation mode of the server, can be either "controller" or "host". This is better thought of as Management or Gameserver nodes. Required on: All

    SERVER_MODEUsers can edit

    required|string|in:controller,host

  • Options: "none", "fatal", "error", "warn", "audit", "info", "verbose" Required on: All

    LOG_LEVELUsers can edit

    required|string|in:none,fatal,error,warn,audit,info,verbose

  • Superadmin account name Required on: Controller

    ADMIN_STRINGUsers can edit

    required|string|max:64A value is required.

  • Host name in the Controller Web UI Required on: Host

    HOST_NAMEUsers can edit

    nullable|string|max:20

  • Connection URL to the Controller server, can be an internal address if you have allocated an additional internal port to the Controller Server. Example: http://yourip:yourport Required on: Host

    CONTROLLER_URLUsers can edit

    nullable|string|max:64

  • Authentication token used to connect to the Controller server, generated through the Controller Web UI. Required on: Host

    CONTROLLER_TOKENUsers can edit

    nullable|string|max:256

  • Clusterio Plugins to install, space separate list. Example: @clusterio/plugin-subspace_storage @clusterio/plugin-global_chat @clusterio/plugin-research_sync @clusterio/plugin-inventory_sync Required on: All

    PLUGINSUsers can edit

    nullable|string|max:512

  • The Name of your Controller server cluster. Required: Controller

    CLUSTER_NAMEUsers can edit

    nullable|string|max:20

Wings

Stop command
^C (SIGINT)
Running when the console shows
Started

Files Wings edits

Wings sets these values in these files before each start.

config-controller.json json

controller~1http_port
{{server.build.default.port}}
controller~1name
{{server.build.env.CLUSTER_NAME}}

config-host.json json

host~1controller_url
{{server.build.env.CONTROLLER_URL}}
host~1controller_token
{{server.build.env.CONTROLLER_TOKEN}}
host~1public_address
{{server.build.default.ip}}

Readme

Clusterio

Introduction

Clusterio (https://github.com/clusterio/clusterio) is a clustered Factorio server manager that provides the tooling for implementing cross server interactions in Factorio. It was previously best known for implementing cross server transfer and cloud storage of items via teleporter chests. But this functionality has been pulled out of Clusterio into its own plugin for Clusterio named Subspace Storage.

By itself Clusterio doesn't change the gameplay in any way, you could even use Clusterio to manage completely vanilla Factorio servers. Plugins do the work of modding in the visible changes into the game, see the Plugins section for ready-made plugins you can install into a Clusterio cluster.

Features

  • Clustered Factorio server management allowing you manage the running of Factorio servers across a fleet of physical servers from both a web interface and a command line interface.

  • User list management for synchronizing in-game admins, whitelisted users, and bans to all the servers in the cluster.

  • Integrated support for exporting statistics for the whole cluster to Prometheus via a single metrics endpoint.

  • Extensive plugin support for adding your own cross server features to Factorio using Clusterio's communication backbone.

Setup

Clusterio uses a Controller/Host system setup, with the Controller server running the Web UI and controlling which Hosts run which Instances.

The Controller server runs a web server that needs to be reachable for cluster management by the user, and by the other nodes to manage them.

The Host server runs the factorio server, and will need any mods manually importing at this time, including the Factorio mods for the Clustorio Library(https://mods.factorio.com/mod/clusterio_lib) and Subspace Storage(https://mods.factorio.com/mod/subspace_storage).

Both only require a single port each.

Server Mode controls if the server is a Controller or Host, and each varaible is labeled as required for Controller, Host or All. Please ensure you fill in all required variables.

Set up the Controller server first, and from there you can generate the Controller URL and Controller Token required for the Host servers to connect.

Additional configuration options can be found in config-Controller.json and config-Host.json as relevant.

Changes to the Cluster will only be written out to the database on a graceful stop.

Server Ports

Clusterio requires a single port

Port default
Controller HTTP 8081
Host Game 34197

Changes

  1. fixie pixie 馃悷

    路 yesBad 路 73a886f

  2. Add standalone games

    路 Daniel Barton 路 74c706a

All changes on GitHub

Problem with this egg?

Open an issue on GitHub. Include your Panel and Wings versions.

Report an issue
Install script 31 lines bash in node:21-bookworm-slim Show 
#!/bin/bash
# Clusterio Installation Script
#
# Server Files: /mnt/server
apt update
apt install -y git curl jq file unzip make gcc g++ python3 python3-dev libtool

mkdir -p /mnt/server
cd /mnt/server

if [ "${USER_UPLOAD}" == "true" ] || [ "${USER_UPLOAD}" == "1" ]; then
    echo -e "assuming user knows what they are doing have a good day."
    exit 0
fi

case "${SERVER_MODE}" in

  "controller")
    echo -e "Initialising Clustorio In Controller mode"
        npm init "@clusterio" -y -- --allow-install-as-root --mode "${SERVER_MODE}" --download-headless --log-level "${LOG_LEVEL}" --admin "${ADMIN_STRING}" --public-address "${SERVER_IP}":"${SERVER_PORT}" --plugins ${PLUGINS}
	;;

  "host")
    echo -e "Initialising Clustorio In Host mode"
	npm init "@clusterio" -y -- --allow-install-as-root --mode "${SERVER_MODE}" --download-headless --log-level "${LOG_LEVEL}" --host-name "${HOST_NAME}" --public-address "${SERVER_IP}" --controller-url "${CONTROLLER_URL}" --controller-token "${CONTROLLER_TOKEN}" --plugins ${PLUGINS}
    ;;
    
esac

echo -e "install complete"
exit 0