Add a guide for managing a cluster

docs/managing-a-cluster.md goes through the day to day tasks in the
web interface: logging in, hosts, instances, saves, mod packs, users
and roles, plugins and logs, each linking to the matching ctl
commands. It explains the data export needed for item icons, names
and mod settings, including that a host with only the headless build
exports no base game icons.

The mod section of the README moves into the guide so there is one
copy of it, and the README points to the guide and the ctl docs.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-11-22 00:00:06 +00:00
1 parent fb93962972
commit 3c03574106
2 files changed
+201 -21

No files matched your search

+7 -21
View File
@@ -223,21 +223,9 @@ See the [readme for @clusterio/controller](/packages/controller/README.md) for m
## Managing Factorio mods ## Managing Factorio mods
Mods in Clusterio are managed as parts of mod packs. Mods in Clusterio are managed as parts of mod packs, which are set up on the Mods page of the web interface and assigned to instances.
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. See [Mod Packs](docs/managing-a-cluster.md#mod-packs) in the Managing a Cluster guide.
Mod Portal downloads require the controller's [Factorio account credentials](docs/configuration.md#controllerfactorio_username) to be configured. To see item icons and names and to edit mod settings in the web interface, data has to be exported from Factorio first, see [Exporting data](docs/managing-a-cluster.md#exporting-data).
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)
Mod settings can be managed under the modpack configuration page in the web UI. For mod settings to show, you first need to run an export. This is done by creating an instance with the modpack assigned, opening the instance page and pressing More -> Export data.
![Export mod configuration data](docs/assets/export_mod_config_data.png)
Once this is done, the mod settings will show up under the modpack configuration page.
![Mod settings configuration in web interface](docs/assets/mod_settings_configuration.png)
## Setting up shared storage ## Setting up shared storage
@@ -258,6 +246,7 @@ Once the controller process is running you can log into the web interface which
The first time a host starts it prints a link for approving it, open the link and click Approve. The first time a host starts it prints a link for approving it, open the link and click Approve.
The basics of setting up a Factorio server from the web interface is to create an instance, assign it to a host and then click start. You can also use the "Connect via Steam" button to launch Factorio directly and connect to the server using Steam's protocol handler. The basics of setting up a Factorio server from the web interface is to create an instance, assign it to a host and then click start. You can also use the "Connect via Steam" button to launch Factorio directly and connect to the server using Steam's protocol handler.
See [Managing a Cluster](docs/managing-a-cluster.md) for a guide to the day to day tasks, like managing saves and mod packs and giving other users access.
### Running via Systemd ### Running via Systemd
@@ -298,12 +287,9 @@ To add the computer back to the cluster start the host again, it asks for approv
## Setting up clusterioctl ## Setting up clusterioctl
There's a command line interface available for Clusterio which is installed separately with the same installer as for the controller and host. There's a command line interface available for Clusterio called clusterioctl.
Run the installer as described in the installation section and choose "Ctl only" as the operating mode to install, you can do this in the same directory as you have installed other Clusterio component(s) to. It is installed separately with the same installer as for the controller and host, by choosing "Ctl only" as the operating mode, you can do this in the same directory as you have installed other Clusterio component(s) to.
The installer will ask for a controller URL and an authentication token, these are the same as you would use to connect to the web interface. See [Clusterioctl](docs/clusterioctl.md#setting-up) for how to set it up and the commands it has.
If you want to use a different user for the command line interface, you can generate an authentication token for an existing user with
npx clusteriocontroller bootstrap generate-user-token <username>
## Known Issues ## Known Issues
+194
View File
@@ -0,0 +1,194 @@
# Managing a Cluster
This guide goes through the day to day tasks of running a cluster from the web interface.
It assumes Clusterio is installed and running, see the [README](/README.md#installation) for how to get there.
Each section ends with the clusterioctl commands for the same task, see [Clusterioctl](clusterioctl.md) for the details of these.
## Logging in
The web interface is hosted by the controller, by default on port 8080.
Log in with an authentication token, the installer prints one for the admin account it creates.
Other users can log in by joining one of the Factorio servers in the cluster if the [Player Auth](/plugins/player_auth/README.md) plugin is installed.
Otherwise a token for a user can be generated on the controller computer with
npx clusteriocontroller bootstrap generate-user-token <username>
A token gives full access to the account it is for until it is revoked with the Revoke token button on the page of the user.
What a user can see and do in the web interface depends on their roles, see [Users and Permissions](#users-and-permissions).
## Hosts
A host is a computer that runs Factorio servers for the cluster.
See [Setting up remote hosts](/README.md#setting-up-remote-hosts) for how to add one.
The Hosts page lists the hosts with their CPU, memory and disk usage.
The page of a host shows the instances assigned to it, its log and its config.
From there it can be restarted, updated, or removed from the cluster with Revoke host access.
ctl: [Hosts](clusterioctl.md#hosts).
## Instances
An instance is a Factorio server along with its config and saves.
Instances are assigned to a host, which is where the server runs and the saves are stored.
### Creating an instance
Click Create on the Instances page and give the instance a name.
Leave Start after creation unticked for now, as the instance needs a host before it can start.
Then open the instance and assign it to a host with the Assign button.
The instance uses the default mod pack set on the Controller page, which is the base game of the newest Factorio version unless changed.
To use a different one pick it under Config -> Factorio -> Mod pack on the instance page, see [Mod Packs](#mod-packs) for setting them up.
ctl: [Create instance](clusterioctl.md#create-instance), [Assign instance to host](clusterioctl.md#assign-instance-to-host).
### Starting and stopping
Click Start on the instance page.
The instance loads the save that was modified last, or creates a new map if it has no saves.
To load a different save, click it in the saves list and use Load save, see [Saves](#saves).
Players connect to the address shown under Public address, or with the Connect via Steam button.
Stop saves the game and shuts the server down.
Start all and Stop all on the Instances page do the same for every instance, start all skips instances with `instance.exclude_from_start_all` set.
An instance can be started automatically when its host starts with `instance.auto_start`, and restarted after a crash with `instance.restart_after_crash`.
ctl: [Start instance](clusterioctl.md#start-instance), [Stop instance](clusterioctl.md#stop-instance), [Start all instances](clusterioctl.md#start-all-instances).
### Changing settings
The Config section at the bottom of the instance page holds the instance settings.
The server name, description, password, player limit and other options from Factorio's server-settings.json are under Factorio -> Settings.
Most of these, like the name, password and player limit, are applied to a running server right away.
See [Instance Configuration](configuration.md#instance-configuration) for every setting.
To share settings between instances, make one instance into a template with Create template and create the other instances from it.
Instances created from a template take every setting they don't set themselves from it, and follow changes made to the template.
ctl: [Config management](clusterioctl.md#config-management).
### Running commands
The Console section on the instance page shows the log of the instance, and commands typed into it are sent to the Factorio server.
This works like the in-game console with admin rights, so `/c` runs Lua and disables achievements.
ctl: [Send RCON command](clusterioctl.md#send-rcon-command).
## Saves
The saves list on the instance page shows the saves stored on the host for that instance.
Click a save to show the actions for it.
Load save starts the instance with that save, and Download, Rename, Copy and Delete do what they say.
Transfer moves or copies the save to another instance, which can be on a different host.
New saves can be made with Create save, which generates a new map, optionally from a seed or a map exchange string.
Saves can also be uploaded with Upload save or by dropping a save file onto the list.
Several saves can be selected at once with the checkboxes to download, transfer or delete them together.
The `_autosave` saves are written by Factorio.
Loading one starts the instance from a copy of it, so the autosave isn't overwritten.
ctl: [Saves](clusterioctl.md#saves).
## Mod Packs
Mods in Clusterio are managed as parts of mod packs.
A mod pack is a list of mods with their versions, and the mod settings to use with them.
Every instance uses one mod pack, and hosts download the mods in it from the controller when the instance starts.
On the Mods page, use Search to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files with Upload.
Mod Portal downloads require the controller's [Factorio account credentials](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 on the Controller page.
![Select mod pack for instance](assets/config_select_mod_pack.png)
Mod settings are changed on the page of the mod pack.
The settings only show up after data has been exported for the mod pack, see the next section.
![Mod settings configuration in web interface](assets/mod_settings_configuration.png)
Mod packs can be shared between clusters with Export to string on the mod pack page and Import string on the Mods page.
ctl: [Mods](clusterioctl.md#mods), [Mod Packs](clusterioctl.md#mod-packs).
### Exporting data
The web interface does not know the names and icons of items, or which settings mods have, until they have been exported from Factorio.
Until then items are shown by their internal name without an icon, and the mod pack page has no settings to edit.
This affects every page that shows items, including the plugin pages of Subspace Storage and Player Sync, which use the export of the default mod pack.
To export the data, assign the mod pack to an instance, stop the instance, and click More -> Export data on the instance page.
The export belongs to the mod pack the instance uses, so do this once for each mod pack.
Run it again after adding or updating mods in the pack.
![Export mod configuration data](assets/export_mod_config_data.png)
The icons of the base game are read from the Factorio install on the host.
The headless build of Factorio has no graphics, so on a host that only has the headless build the export has the names but none of the base game icons, and the host logs a warning about it.
To get the icons, put a full install of the same Factorio version into the `host.factorio_directory` of the host, or export from a host that has one.
Icons from mods are read from the mod files and are exported either way.
The Icon reference link under Inspect exported data on the mod pack page shows everything in the export.
ctl: [Export data](clusterioctl.md#export-data).
## Users and Permissions
### Players
Clusterio creates a user account for every player that joins an instance with save patching enabled.
The Users page lists them with their online time.
The page of a user shows their stats per instance, and has switches for making them an in-game admin, whitelisting them, and banning them.
These lists are shared between all instances that have `factorio.sync_adminlist`, `factorio.sync_whitelist` and `factorio.sync_banlist` turned on, which they are by default.
The whitelist is only enforced on instances with `factorio.enable_whitelist` turned on.
Existing Factorio admin, ban and whitelist files can be imported with Bulk Actions on the Users page, which can also export them.
ctl: [Users](clusterioctl.md#users).
### Granting access to the cluster
Being an in-game admin does not give any access to manage the cluster.
Access to the web interface and clusterioctl is controlled by roles, which are sets of permissions.
There are two roles by default: Cluster Admin, which can do everything, and Player, which can view most of the cluster but not change anything.
New users get the Player role.
To let someone manage part of the cluster, create a role on the Roles page and tick the permissions it should grant.
For example, a role for starting and stopping servers needs `core.instance.start` and `core.instance.stop`, along with the permissions the Player role has for viewing instances.
Then add the role to the user under Roles on the page of the user.
Use the Cluster Admin role for people who should have full control.
The user can then log in as described in [Logging in](#logging-in).
ctl: [Roles](clusterioctl.md#roles), [Set Cluster Roles](clusterioctl.md#set-cluster-roles).
## Plugins and Updates
The Plugins page lists the plugins installed on the controller and each host, with their versions.
If remote updates are enabled, Clusterio and plugins installed from npm can be updated from here, and the Controller and host pages have an Update Clusterio button.
Browse plugins searches npm for plugins, installing them from the web interface needs remote installs to be enabled on the computer.
Installs and updates take effect after a restart, the Plugins page shows which computers are waiting for one.
See [Plugins (Remote)](clusterioctl.md#plugins-remote) for turning remote updates and installs on or off.
Plugins can also be installed on the computer itself, see [Installing Plugins](/README.md#installing-plugins).
## Logs
The Controller page shows the log of the controller, the page of a host the log of that host, and the instance page the log of the instance and its Factorio server.
The log files are stored in the `logs` folder of the controller and are kept for `controller.log_retention_days` days.
ctl: [Logs](clusterioctl.md#logs).