diff --git a/README.md b/README.md index 04f0a500..85a86b4d 100644 --- a/README.md +++ b/README.md @@ -30,76 +30,81 @@ the [1.2.x branch][1.2.x] for instructions on how to install the stable version. ### Table of contents -* [Introduction & methodology](#introduction) +* [Introduction](#introduction) +* [Features](#features) +* [Plugins](#plugins) * [Ubuntu setup](#ubuntu-setup) * [Windows setup](#windows-setup) * [Installing Plugins](#installing-plugins) +* [Configure Master Server](#configure-master-server) + * [Hosting Behind Proxy](#hosting-behind-proxy) + * [Setting up an admin account](#setting-up-an-admin-account) * [Running Clusterio](#running-clusterio) * [Master Server](#master-server) * [Slaves](#slaves) * [Instances](#instances) * [Common problems](#Common-problems) + ## Introduction -Features: +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](https://github.com/clusterio/factorioClusterioMod). -- Entities to send/recieve items - -- Cross dimensional storage - -- Sending of liquids - -- Sending of circuit network signals - -- Inventory combinator to display item levels in the cluster (and epoch time) - -- Reporting of graphs and UPS on master interface (Also has extensive Prometheus reporting) - -Optional extras (see [Plugins](#Plugins)) - -- Have your inventory synchronize across servers - -- Teleport trans from the border of one world to te next - -- Show in-game chat in discord +By itself Clusterio does 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](#plugins) for ready made plugins you can install into +a Clusterio cluster. -Connection diagram: +## Features -![http://i.imgur.com/7FdVfgB.png](http://i.imgur.com/7FdVfgB.png) +- 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. -There can be any number of clients connected to each slave, and any number of slaves connected to a master but there can only be one master server in each cluster. +- User list management for synchronizing in-game admins, whitelisted + users, and bans to all the servers in the cluster. -**How does it work?** +- Integrated support for exporting statistics for the whole cluster to + Prometheus via a single metrics endpoint. -Traditional factorio mods have always been limited by the games deterministic design. This gives us a very bug free and predictable game, but doesn't allow us cool stuff such as internet communication. -Clusterio exploits one of the games logging features, game.write_file and RCON to communicate between servers. Sending an item from one server to another takes this path: +- Extensive plugin support for adding your own cross server features to + Factorio using Clusterio's communication backbone. -1. server1: Chest has stuff in it, write the contents to a file and delete them from the game world -2. client.js on server1: File has stuff in it, parse and send to the master for storage +## Plugins -3. master: server1 gave us stuff, store it in the storage and write some statistics +The heart of Clusterio is its plugin syste. Plugins add functionality +to Factorio servers, Clusterio itself or both. These are the plugins +supported and maintained by the Clusterio developers: -4. server2: get-chest is empty, write a request to file +- [Global Chat](/plugins/global_chat/README.md): share the in-game chat + between servers. +- [Research Sync](/plugins/research_sync/README.md): synchronize + research progress and technologies unlocked between servers. +- [Statistics Exporter](/plugins/statistics_exporter/README.md): collect + in-game statistics from all the servers and makes it available to the + Prometheus endpoint on the master server. +- [Subspace Storage](https://github.com/clusterio/factorioClusterioMod): + Provide shared storage that can transport items between servers via + teleport chests. -5. client.js on server2: Request file has stuff in it, parse and send a request to master for more items of that type +Want to make your own plugin? Check out the documentation on [Writing +Plugins](/docs/writing-plugins.md) for where to start. -6. master: server2 asked for stuff, check if we have enough and how much demand there is, then send however much is appropriate back - -7. client.js on server2: We were allowed to import x of item y, run command /c remote.call("clusterio", "importMany", "{'copper-plate':120}") - -This process works the same for both items and liquids, independent on what mods are used. Yes, modded items are fully supported. - -Clusterio can also do a few other neat things, such as giving you access to epoch time, syncing player inventories between servers, keeping track of playtime (playerManager plugin), teleporting trains between servers (trainTeleports) and exporting tons of factorio related statistics to Prometheus for graphing in grafana. ## Ubuntu setup **Warning**: These instructions are for the unstable master version and is not recommended for use, see [the 1.2.x branch][1.2.x] for how to install the stable version. -Clusterio runs on Node.js v12 and up, v11.13.0+ and v10.16.0+. Node.js itself is not +Clusterio runs on Node.js v12 and up, and v10.16.0+. Node.js itself is not supported on EOL Ubuntu releases so make sure you're on a recent release of Ubuntu. Master and all slaves: @@ -140,7 +145,7 @@ recommended for use, see [the 1.2.x branch][1.2.x] for how to install the stable **Requirements** download and install nodeJS 12 from http://nodejs.org. Clusterio runs on Node.js v12 and -up, v11.13.0+ and v10.16.0+. +up, and v10.16.0+. **Master** @@ -199,10 +204,65 @@ plugins by the absolute path to them, or a relative path that must start with either . or .. (which will then be resolved to an absolute path). -## Running Clusterio +## Configure Master Server -After following the installation instructions you can use the following -commands to run Clusterio. +By default the master server will create a self signed TLS certificate +and listen on HTTPS on port 8443. You can change the port used with the +command + + npx clusteriomaster config set master.https_port 1234 + +If you plan to make your cluster available externally set the address +that it will be accessible under with, for example + + npx clusteriomaster config set master.external_address https://192.0.2.4:8443/ + +Change the url to reflect the IP, protocol, and port the master server +is accessible under, dns names are also supported. If proxyed under a +sub-path include the sub path as well and make sure the URL ends with a +slash. + +You can list the config of the master server with the `npx +clusteriomaster config list` command. See the [readme for +@clusterio/master](/packages/master/README.md) for more +information. + + +### Hosting Behind Proxy + +If you want to host the master server behind a reverse proxy the +recommended setup is to disable HTTPS and host it on a high port +over HTTP to which you point your proxy to. For example to configure +port 8080 as the HTTP port for the master server. + + npx clusteriomaster config set master.https_port # unsets https_port + npx clusteriomaster config set master.http_port 8080 + +The proxy can then forward requests to a sub-path like `/cluster/` to +`http://localhost:8080/`. + +Additianlly WebSocket connections to api/socket relative to the sub-path +the interface is hosted under also needs to be forwarded. See below for +the specifics of setting this up on Apache. + + +#### Apache Config + +To proxy with Apache make sure that proxy_module, proxy_http_module and +proxy_wstunnel_module is loaded in the config, then add the following +directives to wherever is the approriate place for your flavour of +Apache config organization. + +```apache + + ProxyPass "http://localhost:8080/" + + + ProxyPass "ws://localhost:8080/api/socket" + +``` + +Pay attention to the use of trailing slashes, they are important. ### Setting up an admin account @@ -220,7 +280,13 @@ promotes it to a cluster admin. The second one sets up a server under the given user account. -### Running the master Server +## Running Clusterio + +After following the installation and master configuration instructions +you can use the following commands to run Clusterio. + + +### Master Server It's necessary to run the master server in order for anything to work. Once you've completed the setup run the following command to start it @@ -246,8 +312,8 @@ the config for a remote slave you will need to have set the reached on. You can list the config of a slave on the slave itself with the `npx -clusterioslave config list` command. Use `npx clusterioslave config ---help` for more information. +clusterioslave config list` command. See the [readme for +@clusterio/slave](/packages/slave/README.md) for more information. Once the config is set up run the slave with @@ -276,7 +342,8 @@ directory and files needed to run the instance on the given slave. The third line starts the instance, which creates a new save if there are no save games present. -There are many more commands available with clusterioctl. See +There are many more commands available with clusterioctl. See the +[Managing a Cluster](/docs/managing-a-cluster.md) document or `npx clusterioctl --help` for a full list of them. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..71a76b60 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,323 @@ +Configuration +============= + + +Master Configuration +-------------------- + +### master.database_directory + +Directory used to store cluster data to. Needs to be writeable by the +master server. This is also used by plugins to store its data. + +Defaults to "database". + + +### master.http_port + +Port to host HTTP server on. If set to null no HTTP server will be +exposed. At least one of this and master.https_port needs to be set to +a port. + +Defaults to null. + + +### master.https_port + +Port to host HTTPS server on. Uses master.tls_certificate and +master.tls_private_key as the certificate and private key for the HTTPS +server. If set to null no HTTPS server will be exposed. At least one +of this and master.http_port needs to be set to a port. + +Defaults to 8443. + + +### master.external_address + +External address the master server is accessible on. Currently only +used for `clusteriomaster bootstrap create-ctl-config` in order to give +the right url to connect to. This should be a full URL ending with a /. + +Defaults to null meaning assume localhost. + + +### master.tls_certificate + +TLS certificate to use for the HTTPS server when master.https_port is +configured. If neither this nor the configured master.tls_private_key +exists a self signed certificate is automatically created. + +Defaults to "database/certificates/cert.crt". + + +### master.tls_private_key + +TLS private key to use for the HTTPS server when master.https_port is +configured. If neither this nor the configured master.tls_certificate +exists a self signed certificate is automatically created. + +Defaults to "database/certificates/cert.key". + + +### master.tls_bits + +Number of bits to use when creating a self signed certificate. + +Defaults to 2048. + + +### master.auth_secret + +Base64 encoded authentication secret used to verify tokens issued to +slaves, users, and sessions. This should contain 256 bytes of random +data, and if changed will cause all tokens become invalid. Keep this +secret if leaked an attacker could easily compromise the cluster. + +Defaults to null which means generate a secure secret on startup. + + +### master.heartbeat_interval + +Interval in seconds heartbeats are sent out at for WebSocket +connections. If a connection hasn't received a heartbeat in 2 times the +heartbeat interval it will be considered stale and closed. A lower +value means less time between connections going stale and them being +closed. + +Defaults to 60 + + +### master.connector_shutdown_timeout + +Timeout in seconds to use while shutting down the master server for link +sessions that currently don't have an active connection and haven't been +closed down properly. This happens when the network between a slave and +the master server goes down unexpectedly, or the slave goes down without +closing the connection properly either do to crashing or the machine +it's hosted on going down. If the timeout expires the session is +terminated and data loss may occur, if the slave went down this is +unavoidable. + +Defaults to 30. + + +### master.default_role_id + +Role to automatically grant to new users. If null no role is granted. + +Defaults to 1 which correspond to the default Player role. + + +### .enabled + +Whether to enable the given plugin on the master server. Plugins +disabled on the master server will not be loaded on instances. + +Defaults to true. + + +Slave Configuration +------------------- + +### slave.name + +Name of the slave. Shows up in slave lists and is used to reference +this slave in the clusterioctl command line interface. + +Defaults to "New Slave". + + +### slave.id + +Imutable numeric id of the slave which uniquely identifies this slave in +the cluster. + +Defaults to a random 31 bit number. + + +### slave.factorio_directory + +Directory to look for the Factorio server(s) in. This can either point +to a Factorio server directory, or to a directory containing multiple +versions of the Factorio server. + +Defaults to "factorio". + + +### slave.instances_directory + +Directory to store instances in. One sub-directory will be created in +it for each instance assigned to this slave and these sub-directories +will contain logs, saves, and various auto generated configuration files +for the instances. + +Defaults to "instances". + + +### slave.master_url + +URL to connect to the master server to. + +Defaults to "https://localhost:8443/". + + +### slave.master_token + +Access token used for authenticating with the master server. You can +generate an access token with `clusterioctl slave generate-token +--id `, or use the `clusterioctl slave create-config` to +create a new slave config with the correct url and token in it. + +Defaults to "enter token here". + + +### slave.public_address + +External address instances hosted on this slave can be accessed on. +This is used by plugins like Server Select to give the correct address +to switch between instances in-game. + +Defaults to "localhost". + + +### slave.reconnect_delay + +Delay in seconds to wait after connection to the master server is +dropped before attempting to reconnect to it. The actual delay on each +reconnect will be a random number between 0 and this configured value to +avoid all slaves trying to reconnect at the same time. + +Defaults to 5. + + +Instance Configuration +====================== + +### instance.name + +Name of the instance, shown in instance lists and used to reference to this +instance in the clusterioctl command line interface. + +Defaults to "New Instance" + + +### instance.id + +Imutable numeric id of the instance which uniquely identifies this +instance in the cluster. + +Defaluts to a random 31 bit integer. + + +### instance.assigned_slave + +Slave this instance is assigned to. To change this you need to use the +separate assign instance interface. After being assigned to a slave the +directory for the instance is created on the slave. + +Defaults to null meaning not assigned. + + +### factorio.version + +Version of Factorio to use for this instance. Can be a version like +"1.0.0" or special string "latest" meaning the latest version of +Factorio found on the slave. + +Defaults to "latest" + + +### factorio.game_port + +UDP port to run the Factorio server on. If null a random port in the +dynamyc range assigned each time the instance starts. + +Defaults to null + + +### factorio.rcon_port + +TCP port to start the RCON interface on the Factorio server on. If null +a random port in the dynamic range is assigned each time the instance +starts. + +Defaults to null + + +### factorio.rcon_password + +Password to use for the RCON interafec. If null a random secure +password is generated and used each time the instance starts. + +Defaults to null + + +### factorio.enable_save_patching + +Whether to use save patching or not. When enabled lua code is patched +into the game save before starting it. Most plugins require the use of +save patching to function. Turning it off makes it possible to use +Clusterio to run and manage regular vanilla games and scenarios not +compatible with Clusterio. + +Defaults to true + + +### factorio.enable_whitelist + +Turn on the whitelist on the server. + +Defaults to false + + +### factorio.settings + +Object with the settings to put into `server-settings.json` for the +Factorio server. The settings in `data/server-settings.example.json` of +the Factorio installation is used as the base and properties specified +here overrides the properties there. + +Defaults to {"tags":["clusterio"],"auto_pause":false}. + + +### factorio.sync_adminlist + +Synchronize in-game admin list with admin status of the users in +cluster. If enabled Clusterio will generate a new +`server-adminlist.json` on instance startup based on the users in the +cluster with admin status set to true, and keep the admins in sync with +the users that have admin status while the instance is running. + +Defaults to true + + +### factorio.sync_whitelist + +Synchronize in-game whitelist with the whitelisted status of the users +in the cluster. If enabled Clusterio will generate a new +`server-whitelist.json` on instance startup based on the users in the +cluster with whitelisted status set to true, and keep the whitelisted +users in sync with the users that have whitelisted status while the +instance in running. + +Defaults to true + + +### factorio.sync_banlist + +Synchronize in-game banlist with the banned status of users in the +cluster. If enabled Clusterio will generate a new `server-banlist.json` +on instance startup based on users in the cluster with banned status set +to true, and keep the banned users in sync with the users that have the +banned status while the instance is running. + +Defaults to true + + +### .enabled + +Whether to enable the given plugin on the instance. Note that plugins +need to be enabled on the master server in order for them to be loaded +on instances. + +Defaults to true diff --git a/docs/contributing.md b/docs/contributing.md index 694db86a..beca0b72 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -187,7 +187,7 @@ of this log should be self explanatory, please follow it carefully. Supported Node.js and Factorio Versions --------------------------------------- -Clusterio run on Node.js v12 and up, v11.13.0+ and v10.16.0+, make sure +Clusterio run on Node.js v12 and up, and v10 from v10.16.0, make sure to check that the Node builtin API's and npm packages you use are supported on these versions. The Travis CI tests are runned on whatever version of Node.js v10 is the default, which at the time of writing is diff --git a/docs/maniging-a-cluster.md b/docs/managing-a-cluster.md similarity index 98% rename from docs/maniging-a-cluster.md rename to docs/managing-a-cluster.md index d8e45881..ef58dbf0 100644 --- a/docs/maniging-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -1,7 +1,7 @@ Managing a Cluster ================== -Clusterio clusers are managed through the master server by using the +Clusterio clusters are managed through the master server by using the `clusterioctl` command line interface which is invoked by running `npx clusterioctl ` in the clusterio directory. This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should diff --git a/package.json b/package.json index 22cd7e21..bf526b27 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ ] }, "engines": { - "node": ">=10.16 <11 || >= 11.13" + "node": ">=10.16 <11 || >= 12" }, "devDependencies": { "@clusterio/ctl": "file:./packages/ctl", diff --git a/packages/ctl/README.md b/packages/ctl/README.md new file mode 100644 index 00000000..8bae7719 --- /dev/null +++ b/packages/ctl/README.md @@ -0,0 +1,108 @@ +Clusterio Command Line Interface +================================ + +Provides a command line interface for managing a Clusterio cluster. + +Note that this document only describes the options and commands for +managing clusterioctl itself, see [Managing a +cluster](/docs/managing-a-cluster.md) for the available commands used +for managing a cluster. + + +Usage +----- + + npx clusterioctl + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to ctl. Defaults to `plugin-list.json` + and will be created if it does not exist. See the `plugin` command + for managing this list. + + * `--config ` JSON file to use for storing configuration for + ctl. Defaults to `config-control.json` and will be created if it + does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by ctl. The available plugins +will be automatically loaded and the commands they provide will be added +to the ctl utility. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusterioctl plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusterioctl plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config-control` + +Manage the ctl configuration. This allows setting the url and token to +the master server to manage. + + +#### `config-control set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration. + + +#### `config-control show ` + +Shows the value for a single config entry. + + +#### `config-control list` + +Lists up all configuration entries with their currently configured values. + + +## See Also + +[Managing a cluster](/docs/managing-a-cluster.md) for the available +commands used for managing a cluster. + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/packages/ctl/package.json b/packages/ctl/package.json index da0dc2cb..a62db866 100644 --- a/packages/ctl/package.json +++ b/packages/ctl/package.json @@ -15,7 +15,7 @@ "factorio" ], "engines": { - "node": ">=10.16 <11 || >= 11.13" + "node": ">=10.16 <11 || >= 12" }, "dependencies": { "@clusterio/lib": "^2.0.0-alpha.0", diff --git a/packages/lib/README.md b/packages/lib/README.md new file mode 100644 index 00000000..db7a33ed --- /dev/null +++ b/packages/lib/README.md @@ -0,0 +1,8 @@ +Common Library for Clusterio +============================ + +This package contains functionality shared between master, slave, ctl +and/or plugins of Clusterio. + +See [the Clusterio repository](https://github.com/clusterio/factorioClusterio) +for more inforation on Clusterio. diff --git a/packages/lib/package.json b/packages/lib/package.json index e4617f7d..ac1af70a 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -8,7 +8,7 @@ "factorio" ], "engines": { - "node": ">=10.16 <11 || >= 11.13" + "node": ">=10.16 <11 || >= 12" }, "dependencies": { "ajv": "^6.12.6", diff --git a/packages/master/README.md b/packages/master/README.md new file mode 100644 index 00000000..99e76433 --- /dev/null +++ b/packages/master/README.md @@ -0,0 +1,128 @@ +Clusterio Master Server +======================= + +Communication hub for Clusterio clusters. The master server forwards +data between Clusterio slaves connected to it and allows the cluster to +be remotely managed through WebSocket connections to it either by using +the included web interface or the Clusterio ctl command line utility. + + +Usage +----- + + npx clusteriomaster + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to the master server. Defaults to + `plugin-list.json` and will be created if it does not exist. See the + `plugin` command for managing this list. + + * `--config ` JSON file to use for storing configuration for the + master server. Defaults to `config-master.json` and will be created + if it does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by the master server. The +available plugins will be loaded unless they have been disabled in the +configuration, see the config command for disabling plugins. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusteriomaster plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusteriomaster plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config` + +Manage the master server configuration offline. This should only be +used when the master server is stopped, otherwise the config read might +be out of date and config changes will be overwritten when the master +server shuts down. + + +#### `config set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration entries. + + +#### `config show ` + +Shows the value for a single config entry. + + +#### `config list` + +Lists up all configuration entries with their currently configured values. + + +### `bootstrap` + +Commands for setting up initial admin acount and access to the cluster. + + +#### `bootstrap create-admin ` + +Creates a new user account with the given name if it does not already +exist in the cluster and grant it full cluster admin permission. You +should be using your own Factorio multiplayer username here. + + +#### `bootstrap create-ctl-config ` + +Creates a clusterioctl config for the given user with url and token set +up for connecting to the cluster. + + +### `run` + +Runs the master server. + + +## See Also + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/packages/master/package.json b/packages/master/package.json index 0db50627..c871129a 100644 --- a/packages/master/package.json +++ b/packages/master/package.json @@ -16,7 +16,7 @@ "factorio" ], "engines": { - "node": ">=10.16 <11 || >= 11.13" + "node": ">=10.16 <11 || >= 12" }, "dependencies": { "@clusterio/lib": "^2.0.0-alpha.0", diff --git a/packages/slave/README.md b/packages/slave/README.md new file mode 100644 index 00000000..da8271aa --- /dev/null +++ b/packages/slave/README.md @@ -0,0 +1,111 @@ +Clusterio Slave +=============== + +Node hosting Factorio servers in a Clusterio cluster. Clusterio slaves +connect to the master server and waits for commands from the master +server to start up and stop instances. A cluster can have any number of +slaves in it located on different computers, and each slave can host any +number of instances each of which is a Factorio server that talks with +the rest of the cluster. + + +Usage +----- + + npx clusterioslave + +Common options: + + * `--plugin-list ` JSON file to use for storing the list of + plugins that are available to the slave. Defaults to + `plugin-list.json` and will be created if it does not exist. See the + `plugin` command for managing this list. + + * `--config ` JSON file to use for storing configuration for the + slave. Defaults to `config-slave.json` and will be created if it + does not exist. See the `config` command for inspecting and + modifying the configuration. + + +### `plugin ` + +Configure plugins available to be loaded by the slave. The available +plugins will be loaded unless they have been disabled in the +configuration, see the config command for disabling plugins. + + +#### `plugin add ` + +Add plugin either by require path or relative/absolute path to the +plugin directory. A relative path must start with ./ or ../ (or .\ and +..\ on Windows) otherwise it will be assumed to be a require path for an +installed package in node_modules. + +For example, installing the Subspace Storage plugin: + + npm install @clusterio/plugin-subspace_storage + npx clusterioslave plugin add @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin remove ` + +Remove a plugin by its name. This should be done before uninstalling +the plugin, otherwise there will be an error when Clusterio tries to +load the info from the plugin. Removing and unistalling a plugin is +usually not neccessary as the functions provided by the plugin can be +disabled in the config. + +For example, uninstalling the Subspace Storage plugin: + + npx clusterioslave plugin remove subspace_storage + npm uninstall @clusterio/plugin-subspace_storage + +Since the `plugin-list.json` is shared between master, slave and ctl you +usually only need to do this once per machine. + + +#### `plugin list` + +Lists the plugins set up to be available by name followed by path. + + +### `config` + +Manage the slave configuration offline. This should only be used when +the slave is stopped, otherwise the config read might be out of date and +config changes will be overwritten when the slave shuts down. + + +#### `config set [value]` + +Set a config entry to the given value. If value is not provided the +entry is set to null. If the config entry is of type object the value +must be a valid JSON serialization of an object. + +See docs/configuration.md in the main repositiory for the available +configuration. + + +#### `config show ` + +Shows the value for a single config entry. + + +#### `config list` + +Lists up all configuration entries with their currently configured values. + + +### `run` + +Runs the slave. + + +## See Also + +[The Clusterio +repository](https://github.com/clusterio/factorioClusterio) +for instructions on how to set up a cluster. diff --git a/packages/slave/package.json b/packages/slave/package.json index 997fd3ae..532fc937 100644 --- a/packages/slave/package.json +++ b/packages/slave/package.json @@ -15,7 +15,7 @@ "factorio" ], "engines": { - "node": ">=10.16 <11 || >= 11.13" + "node": ">=10.16 <11 || >= 12" }, "dependencies": { "@clusterio/lib": "^2.0.0-alpha.0", diff --git a/plugins/global_chat/README.md b/plugins/global_chat/README.md new file mode 100644 index 00000000..df66f9f5 --- /dev/null +++ b/plugins/global_chat/README.md @@ -0,0 +1,16 @@ +Clusterio Global Chat Plugin +============================ + +Plugin sharing the in-game chat between instances. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-global_chat + npx clusteriomaster plugin add @clusterio/plugin-global_chat + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/research_sync/README.md b/plugins/research_sync/README.md new file mode 100644 index 00000000..6c13adf0 --- /dev/null +++ b/plugins/research_sync/README.md @@ -0,0 +1,17 @@ +Clusterio Research Sync Plugin +============================== + +Plugin synchronizing research progress between instances and the +cluster. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-research_sync + npx clusteriomaster plugin add @clusterio/plugin-research_sync + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/statistics_exporter/README.md b/plugins/statistics_exporter/README.md new file mode 100644 index 00000000..42b6b81a --- /dev/null +++ b/plugins/statistics_exporter/README.md @@ -0,0 +1,18 @@ +Clusterio Statistics Exporter Plugin +==================================== + +Plugin exporting item production, fluid production, kill count, entity +build and poluttion statistics to the Prometheus integration to +Clusterio. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-statistics_exporter + npx clusteriomaster plugin add @clusterio/plugin-statistics_exporter + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively. diff --git a/plugins/subspace_storage/README.md b/plugins/subspace_storage/README.md new file mode 100644 index 00000000..dd4ba2ee --- /dev/null +++ b/plugins/subspace_storage/README.md @@ -0,0 +1,16 @@ +Clusterio Subspace Storage Plugin +================================= + +Plugin for the Subpsace Storage mod. + + +Installation +============ + +Run the following commands in the folder Clusterio is installed to: + + npm install @clusterio/plugin-subspace_storage + npx clusteriomaster plugin add @clusterio/plugin-subspace_storage + +Substitute clusteriomaster with clusterioslave or clusterioctl if this a +dedicate slave or ctl installation respectively.