From 7467fa6b8f5a76065f676b42d02f5a8b11b42081 Mon Sep 17 00:00:00 2001 From: Arvids Godjuks Date: Thu, 15 Oct 2026 15:21:35 +0300 Subject: [PATCH] Refresh installation and stable release documentation (#1086) Refresh installation and stable release documentation --- CHANGELOG.md | 2 +- README.md | 41 ++++++++++++------------ docs/contributing.md | 15 +++++---- docs/managing-a-cluster.md | 9 +++--- docs/migrating-from-2.0.0-alpha.13.md | 46 --------------------------- docs/release-workflow.md | 27 ++++++++++++---- docs/writing-plugins.md | 10 +++--- packages/create/README.md | 3 +- 8 files changed, 64 insertions(+), 89 deletions(-) delete mode 100644 docs/migrating-from-2.0.0-alpha.13.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b3b75a9e..196172dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -673,7 +673,7 @@ Many thanks to the following for contributing to this release: ## Version 2.0.0-alpha.14 This release does not retain backwards compatibility with 2.0.0-alpha.13 meaning all parts of the cluster needs to updated at the same time. -See the [migration guide](/docs/migrating-from-2.0.0-alpha.13.md) for how to update. +See the [migration guide](https://github.com/clusterio/clusterio/blob/e0755cb4ee7bce0068c844ab6271da481a843e62/docs/migrating-from-2.0.0-alpha.13.md) for how to update. ### Major Features diff --git a/README.md b/README.md index 15425bf8..b31864fa 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Discord for development/support/play: https://discord.gg/5XuDkje ## Important notice Clusterio 2.0 is the current stable release and requires Node.js 22 or newer. +For new installations, use the latest Node.js LTS release (see [Installation](#installation)). The previous stable series is no longer supported. If you are upgrading from a 2.0 alpha, review the [changelog](CHANGELOG.md) before upgrading. Plugin authors should also follow the [2.0 migration guide](docs/devs/plugin-migration-to-2.0.md). @@ -41,7 +42,7 @@ Plugin authors should also follow the [2.0 migration guide](docs/devs/plugin-mig * [Setting up remote hosts](#setting-up-remote-hosts) * [Setting up clusterioctl](#setting-up-clusterioctl) * [Known issues](#known-issues) -* [Common problems](#Common-problems) +* [Common problems](#common-problems) ## Introduction @@ -96,8 +97,9 @@ Note that from 2.0 onwards minor versions of Clusterio may contain breaking chan ## Installation -Clusterio runs on all LTS version of NodeJS, it is distributed via npm and comes with a guided install script. -If you already have a recent Node.js installed, you can set it up in a new directory with: +Install the latest [Node.js LTS release](https://nodejs.org/en/download), which is recommended for new Clusterio installations. +Clusterio is distributed via npm and comes with a guided install script. +If you already have a supported Node.js version installed, you can set it up in a new directory with: npm init "@clusterio" @@ -106,12 +108,14 @@ Check out all our of decisions for [node, factorio, and operation support](/docs ### Ubuntu setup -1. Install Node.js v18 or higher. - Note the version of Node.js provided by the Ubuntu/debian repos are too old and you will have to use the nodesource PPA +1. Install the latest Node.js LTS release using the NodeSource repository for Ubuntu/Debian. + The distribution's default repository may provide an older version. - curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - &&\ + curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - &&\ sudo apt-get install -y nodejs + Verify the installation with `node --version` and `npm --version`. + 2. Log in as the user you wish to install Clusterio as (do not use root), and then create a new directory and run the Clusterio installer: mkdir clusterio @@ -143,7 +147,7 @@ Your instances (save files etc) will be stored there. ### Windows setup -1. Download and install the latest LTS release from http://nodejs.org. +1. Download and install the latest [Node.js LTS release](https://nodejs.org/en/download). 2. Create a new empty directory for the installation and navigate into it. Open a PowerShell window in this new directory by Shift+Right clicking inside it and choosing "Open PowerShell window here" and then run the following command. @@ -157,7 +161,8 @@ Your instances (save files etc) will be stored there. ### MacOS Setup -1. Install the latest Node.js LTS release from http://nodejs.org or use brew (`brew install node`). +1. Install the latest [Node.js LTS release](https://nodejs.org/en/download). + If you use [nvm](https://github.com/nvm-sh/nvm#installing-and-updating), run `nvm install --lts`. 2. Open Terminal or Command prompt in the directory you want to install to and run the following commands. @@ -211,7 +216,11 @@ See the [readme for @clusterio/controller](/packages/controller/README.md) for m ## Managing Factorio mods -Mods in clusterio are managed as parts of modpacks. There is currently no mod portal integration, so you first need to navigate to the mods section of the web UI and upload your mods. You can then create a modpack from the uploaded mods by navigating to the mods page, hitting `create`. Once you have a modpack, you can assign it to an instance under Instance config -> Factorio -> Mod pack. You can also set a default modpack for new instances in the controller settings. +Mods in Clusterio are managed as parts of mod packs. +On the Mods page of the web interface, use **Search** to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files directly. +Mod Portal downloads require the controller's [Factorio account credentials](docs/configuration.md#controllerfactorio_username) to be configured. +Use **Create** in the Mod Packs section to create a mod pack, then add the mods you want to use. +Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances in the controller settings. ![Select mod pack for instance](docs/assets/config_select_mod_pack.png) @@ -227,7 +236,9 @@ Once this is done, the mod settings will show up under the modpack configuration ## Setting up shared storage The chests teleporting items to and from the shared storage on the controller has been moved into the Subspace Storage mod and plugin. -To get this to work you will need to install the Subspace Storage plugin and copy the [Subspace Storage mod](https://mods.factorio.com/mod/subspace_storage) and the [Clusterio Lib mod](https://mods.factorio.com/mod/clusterio_lib) into the `sharedMods` folder on each host installation. +To get this to work, install the Subspace Storage plugin on the controller and hosts using the [plugin installation instructions](#installing-plugins). +Download or upload the [Subspace Storage mod](https://mods.factorio.com/mod/subspace_storage) and the [Clusterio Lib mod](https://mods.factorio.com/mod/clusterio_lib) to the controller, add them to a mod pack, and assign it to each participating instance as described in [Managing Factorio mods](#managing-factorio-mods). +Hosts fetch the mods from the controller and synchronize each instance's mods folder with its assigned mod pack when the instance starts. Do not install the [Clusterio mod](https://mods.factorio.com/mod/clusterio), this was for the old 1.2.x version of Clusterio and is not compatible with Clusterio 2.0. @@ -279,16 +290,6 @@ If you want to use a different user for the command line interface, you can gene This should be ignored as it does not indicate an error occured. - After updating Factorio you may get the error `Error: Expected empty response but got "Cannot execute command. Error: [string "clusterio_private.update_instance(..."]:1: attempt to index global 'clusterio_private' (a nil value)?` on instance start. This is due to Factorio applying a migration replacing the patched content of the save with the original scenario, attempting to start the instance again should resolve the issue. -- In the mod pack view of the web interface the "base" mod is displayed with an error complaining about the mod being missing from the controller storage. - This is due to the "base" mod currently not being connectly handled as a built-in mod to Factorio in the web interface, this error message should be ignored. -- After migrating from Alpha 13 to Alpha 14 running an instance data export fails with the error `Upload failed: 401 Unauthorized` due to the host token being issued to a slave. - To workaround this find the id of the host in the host config and generate a new host token with the same id. - Stop the host and replace the value of the `host.controller_token` field in `config-host.json` with the new host token before starting it up again. -- After migrating from Alpha 13 to Alpha 14 you get kicked out from the web interface due to the master to controller rename. - If you don't have the authentication token readily available you can manually migrate the token by opening the Inspect/Developer Tools on the page and running the following piece of JavaScript in the Console: - ``` - localStorage.controller_token = localStorage.master_token - ``` ## Common problems diff --git a/docs/contributing.md b/docs/contributing.md index a2067658..227f3558 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -19,7 +19,7 @@ Although, we recomend checking out out our [past decisions](/docs/decisions.md) - [Updating Your GitHub Fork](#updating-your-github-fork) - [Publishing releases to npm](#publishing-releases-to-npm) - [Changelog](#changelog) -- [Supported Node.js and Factorio Version](#supported-node.js-and-factorio-version) +- [Supported Node.js and Factorio Versions](#supported-nodejs-and-factorio-versions) - [Code Style](#code-style) - [Naming Style](#naming-style) - [Units](#units) @@ -200,12 +200,15 @@ The format of this log should be self explanatory, please follow it carefully. P ## Supported Node.js and Factorio Versions -Clusterio run on Node.js v18 and up, make sure to check that the Node builtin API's and npm packages you use are supported on these versions. -The GitHub Actions tests are run on whatever version of Node.js v18 and v20 is the default. +Clusterio requires Node.js 22 or newer and supports LTS releases in their active and maintenance phases. +For a new development environment, install the latest LTS release using the [installation instructions](../README.md#installation). +Make sure the Node.js built-in APIs and npm packages you use remain compatible with the supported versions. +The GitHub Actions tests currently run on Node.js 24 and 26 across the Factorio matrix, with Node.js 22 used for coverage; see the [CI workflow](../.github/workflows/node.js.yml) for the version matrix. -For Factorio Clusterio 2.0 aims to support version 0.17.69 and up, including the latest experimental release. -It's recommended that you use the lua API reference for 0.17.69, as there's no information on what version Factorio API's were introduced in. -The GitHub Actions tests are run against the latest experimental release. +For Factorio, active support covers the latest stable version and the previous major version, using version lines such as 2.1, 2.0 and 1.1 as described in the [Factorio support policy](decisions.md#factorio). +Older versions from 0.17 onwards receive passive support where it does not restrict actively supported versions. +Check the Lua API documentation for the Factorio versions your changes target and preserve compatibility with the actively supported versions. +The GitHub Actions tests use pinned Factorio releases; see the [CI workflow](../.github/workflows/node.js.yml) for the current version matrix. Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability). diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index 66aaa3ff..e1883443 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -30,9 +30,10 @@ Create a host config. `--id` id the host id. `--name` is the host name. `--gener ### Update Clusterio - ctl> host update [--id ] [--name ] [--restart] + ctl> host update [--all] [--restart] -If remote updates are enabled on the host, this will attempt to update `@clusterio/host` on the machine. Changes will not be applied until the host is restarted. If the `--restart` flag is provided, the host will automatically restart once the update is complete. +Specify the host by name or ID. +If remote updates are enabled on the host, this will attempt to update `@clusterio/host` on the machine. Add `--all` to also update all npm-installed plugins. Changes will not be applied until the host is restarted. If the `--restart` flag is provided, the host will automatically restart once the update is complete. Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the following command locally while the host is offline: @@ -40,7 +41,7 @@ Remote updates are enabled by default but can be disabled on a per-machine basis The controller also supports remote updates, following the same logic. The corresponding commands are: - ctl> controller update [--restart] + ctl> controller update [--all] [--restart] controller> config set controller.allow_remote_updates true/false ### Mark restart required @@ -116,7 +117,7 @@ Edit instance config in a text editor. Once file is saved and editor has been ex ### Assign instance to host - ctl> instace assign [host] + ctl> instance assign [host] Assigns instance to host. `instance` is instance to assign, `host` is host to assign to. If `host` is not provided, instance will be unassigned. diff --git a/docs/migrating-from-2.0.0-alpha.13.md b/docs/migrating-from-2.0.0-alpha.13.md deleted file mode 100644 index 355db4b8..00000000 --- a/docs/migrating-from-2.0.0-alpha.13.md +++ /dev/null @@ -1,46 +0,0 @@ -# Migrating from 2.0.0-alpha.13 to 2.0.0-alpha.14 - -Alpha 14 comes with significant breaking changes for existing clusters, most notably the rename of master and slave to controller and host. -Please study the entire migration guide carefully before attempting to update an existing cluster. - -## Before updating - -If you're using mods you need to create mod pack string for the mod configurations you're currently running. -You can do this by running the follow RCON command on an instance that is currently running the mod configuration you want to use (you can also run this command in single player and find the string printed in Factorio's [Log file](https://wiki.factorio.com/Log_file)): - - /sc local m={name="pack",description="",factorio_version=game.active_mods.base,mods={},settings={startup={},["runtime-global"]={},["runtime-per-user"]={}}} for n,v in pairs(game.active_mods) do table.insert(m.mods,{name=n,enabled=true,version=v}) end local function set(s,c) for n,v in pairs(s) do m.settings[c][n]=v end end set(settings.startup,"startup") set(settings.global,"runtime-global") if game.player then set(game.player.mod_settings,"runtime-per-user") else set(settings.player,"runtime-per-user") end local e=game.encode_string(game.table_to_json(m)) log(e) rcon.print(e) - -If you for some reason want to run this function in 2.0+, use the following command: - - /sc local a={name="pack",description="",factorio_version=script.active_mods.base,mods={},settings={startup={},["runtime-global"]={},["runtime-per-user"]={}}}for b,c in pairs(script.active_mods)do table.insert(a.mods,{name=b,enabled=true,version=c})end;local function d(e,f)for b,c in pairs(e)do a.settings[f][b]=c end end;d(settings.startup,"startup")d(settings.global,"runtime-global")if game.player then d(game.player.mod_settings,"runtime-per-user")else d(settings.player,"runtime-per-user")end;local g=helpers.encode_string(helpers.table_to_json(a))log(g)rcon.print(g) - -This should produce a [Mod Pack String](https://forums.factorio.com/viewtopic.php?f=96&t=103578) which you need to copy and paste somewhere to keep it for later. -Mod Pack strings looks something like this: - - eNqFketuwyAMhd/Fv0OUVpW25lWmqSLESdAIRNh0l4h3n9mlitZt5QdCx/7so8MKXs8ILSzaPEEFPZKJdmEbvIgiDNpwiDaczhjpU93Vu/r+Tmpz6Anah/V7RqcJRUavO4c9tBwTVnAF5upCGJeIsYx3tvsPbQTdb0lKHYlnPJHY0+ONvcdjvW8gP1ZAyGz9KL5XINaR0yLPXEFMnu2ManSh0+6j/GOFitqXG4mjNSUidVm5wlm7JMYG7Qhl3BX8FjyqZ9vztOk+NM2fvRPaceLbzbN+UejQFFOWXzfArvk6v2HWD9ZLv5JfxA1UwsubPBaMKhHGklLO76vAwfQ= - -If you have multiple mod configuration create a mod pack string for each and note them down. - -Double check that you are on a supported version of Node.js by running `node --version`, the version should be v18 or later, if not you will need to update Node.js before continuing. - - -## Migrate installations - -**Note:** Check that plugins you are using have updates avaialble for alpha 14 before attempting to update, if they do not either wait for the plugin to be updated or uninstall the plugin from all places it is installed on first. - -Shutdown all slaves and the master server and then migrate each installations by running the following command: - - npm exec @clusterio/create -y -- --migrate-rename --log-level=verbose - -This will convert the existing installation's usage of the master and slave names in packages, configs, database and logs to the new controller and host terms and update the installed packages. - -If you're using systemd then copy the generated clusteriocontroller.service and/or clusteriohost.service files from the systemd folder to /etc/systemd/system/ and remove the old clusteriomaster.service and clusterioslave.service files. - -Once the installations have been migrated start up the controller and hosts again. - - -## Post installation - -Import the Mod Pack strings that was created beforehand on the controller and upload the mods needed by those mod packs to the controller. -You can assign a default mod pack in the controller config which instances use by default or set the mod pack on the per instance basis in the instance config. -Once you have assigned a mod pack to an instance run a data export on the instance in order to properly populate the mod settings in the mod and get item icons and item names resolved in the web interface. diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 188a5f6e..0ac12a39 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -28,24 +28,37 @@ The steps below describe publishing npm packages manually instead. git status ``` -2. Bump the version in the `package.json` files +2. Create a release branch and bump the version in the `package.json` files. The commands below use 2.0.1 to 2.0.2 as an example; substitute the versions for the release you are preparing. ```sh - sed -i 's/2\.0\.0-alpha\.XX/2\.0\.0-alpha\.YY/' {packages,plugins}/*/package.json - ```` + git switch -c release/2.0.2 + sed -i 's/"version": "2\.0\.1"/"version": "2.0.2"/' {packages,plugins}/*/package.json + pnpm install --no-frozen-lockfile + ``` -3. Tag and push the release to github +3. Review and commit the version and changelog changes, then open and merge a release pull request. ```sh git add -p - git commit -m v2.0.0-alpha.XX - git tag v2.0.0-alpha.XX + git commit -m "Prepare 2.0.2 release" ``` -4. Perform a clean install and publish the packages. +4. After the release pull request is merged, tag the merged commit and push the tag. + + ```sh + git switch master + git pull --ff-only upstream master + git tag v2.0.2 + git push upstream v2.0.2 + ``` + +5. For manual publication, perform a clean install and publish the packages. For automated publication, publish the GitHub release as described above instead. + + The repository does not track `pnpm-lock.yaml`, so allow pnpm to generate or update it during installation. ```sh pnpm clean + pnpm install --no-frozen-lockfile pnpm -r --filter='./packages/*' --filter='./plugins/*' --fail-if-no-match publish ``` diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 9531ad82..a1c6cb83 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -89,8 +89,10 @@ export const plugin = { The following properties are recognized: **name**: - Internal name of the plugin. - Must be the same as the plugin's directory name + Stable internal identifier of the plugin, used as its key in the plugin list. + For local plugins automatically discovered under `plugins/` or `external_plugins/`, it must match the plugin's directory name. + It does not have to match the npm package name. + For example, the package `@clusterio/plugin-subspace_storage` declares the name `subspace_storage`. **title**: Name of the plugin as shown to users. @@ -114,8 +116,8 @@ The following properties are recognized: This is an optional parameter. A plugin can be made that only runs on the controller. -**ControllerConfigGroup**: - Object mapping controller configuration fields to `FieldDefinitions`for this plugin. +**controllerConfigFields**: + Object mapping controller configuration fields to `FieldDefinition` objects for this plugin. See [Plugin Configuration](#plugin-configuration) **ctlEntrypoint**: diff --git a/packages/create/README.md b/packages/create/README.md index a56d579c..2483f03b 100644 --- a/packages/create/README.md +++ b/packages/create/README.md @@ -2,4 +2,5 @@ Installer for Clusterio. -See [the Clusterio README.md](https://github.com/clusterio/clusterio#readme) the for installation guide. +Install the latest [Node.js LTS release](https://nodejs.org/en/download) before running the installer. +See [the Clusterio installation guide](https://github.com/clusterio/clusterio#installation) for platform-specific instructions.