From b60e8c45ffa702686dfb904dcc9aef4460df8ecf Mon Sep 17 00:00:00 2001 From: Florian Kinder Date: Mon, 2 Nov 2026 16:20:57 +0100 Subject: [PATCH 1/2] Clarify Compose deployment and safe settings provisioning --- README.md | 132 +++++++++++++++++------------- docker-compose.yml | 17 ++-- docker/docker-compose.yml | 26 +++--- tests/test_documented_settings.py | 76 +++++++++++++++++ 4 files changed, 174 insertions(+), 77 deletions(-) create mode 100644 tests/test_documented_settings.py diff --git a/README.md b/README.md index 83f35ae4..fffd1e90 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ * `latest` - most up-to-date version (may be experimental). * `stable` - version declared stable on [factorio.com](https://www.factorio.com) ([FFF-435 Since 2.0 versions gets released as experimental first, once stable it will be marked as stable](https://factorio.com/blog/post/fff-435)). +* `stable-x.y.z` - a specific stable release; constrain update tools to this prefix to exclude experimental releases. Rootless equivalents end in `-rootless`. * `0.x` - latest version in a branch. * `0.x.y` - a specific version. * `0.x-z` - incremental fix for that version. @@ -194,21 +195,11 @@ docker run -d \ MyScenarioName ``` -### Converting Scenarios to Regular Maps +### Converting Scenarios to Regular Maps (deprecated) -If you would like to export your scenario to a saved map, you can use the example entrypoint similar to the Scenario usage above. Factorio will run once, converting the Scenario to a saved Map in your saves directory. A restart of the docker image using the standard options will then load that map, just as if the scenario were just started by the Scenarios example noted above. +The legacy `/scenario2map.sh` wrapper is retained for compatibility, but is deprecated for new deployments. Factorio's `--scenario2map` operation does not apply `map-gen-settings.json` or `map-settings.json`; copying those files does not make conversion honor them. See the [upstream explanation](https://forums.factorio.com/viewtopic.php?f=23&t=69377&p=422321#p422321). -```shell -docker run -d \ - -p 34197:34197/udp \ - -p 27015:27015/tcp \ - -v /opt/factorio:/factorio \ - --name factorio \ - --restart=unless-stopped \ - --entrypoint "/scenario2map.sh" \ - factoriotools/factorio - MyScenarioName -``` +Instead, use `/scenario.sh` as described above to start a scenario with the desired map settings, then save the running world through the console or RCON (`/server-save`). After confirming the save completed, stop the container and use the normal entrypoint to load that save. Keep a backup before changing an existing world. ### RCON @@ -253,30 +244,43 @@ Create file `config/server-adminlist.json` and add the adminlisted users. ### Customize configuration files (0.17.x+) -Out-of-the box, factorio does not support environment variables inside the configuration files. A workaround is the usage of `envsubst` which generates the configuration files dynamically during startup from environment variables set in docker-compose: +Factorio does not expand environment variables inside JSON. Prefer mounting a complete settings file (see `SERVER_SETTINGS_FILE` below). If you need per-instance values from Compose, the image already includes `jq`, which safely encodes quotes, backslashes and newlines instead of doing raw text substitution. -Example which replaces the server-settings.json: +First create a **complete, valid** `server-settings.json` template, for example by copying `data/config/server-settings.json` after the initial startup. The following example mounts that template read-only and renders a separate settings file on every start. Supplied variables override the template; unset variables preserve its values. This intentionally regenerates the output file: edit the template, not the generated copy. + ```yaml -factorio_1: - image: factoriotools/factorio - ports: - - "34197:34197/udp" - volumes: - - /opt/factorio:/factorio - - ./server-settings.json:/server-settings.json - environment: - - INSTANCE_NAME=Your Instance's Name - - INSTANCE_DESC=Your Instance's Description - entrypoint: /bin/sh -c "mkdir -p /factorio/config && envsubst < /server-settings.json > /factorio/config/server-settings.json && exec /docker-entrypoint.sh" +services: + factorio: + image: factoriotools/factorio:stable + ports: + - "34197:34197/udp" + volumes: + - ./data:/factorio + - ./server-settings.json:/server-settings.template.json:ro + environment: + INSTANCE_NAME: "My Factorio server" + INSTANCE_DESC: "A server configured through Compose" + # Optional: USERNAME, TOKEN and GAME_PASSWORD override the matching fields. + # Keep credentials out of version control. + entrypoint: + - /bin/sh + - -ec + - | + mkdir -p /factorio/config + jq ' + .name = (env.INSTANCE_NAME // .name) | + .description = (env.INSTANCE_DESC // .description) | + .username = (env.USERNAME // .username) | + .token = (env.TOKEN // .token) | + .game_password = (env.GAME_PASSWORD // .game_password) + ' /server-settings.template.json > /factorio/config/server-settings.json.tmp + mv /factorio/config/server-settings.json.tmp /factorio/config/server-settings.json + exec /docker-entrypoint.sh ``` + -The `server-settings.json` file may then contain the variable references like this: - -```json -"name": "${INSTANCE_NAME}", -"description": "${INSTANCE_DESC}", -``` +These settings variables are consumed by this example wrapper, not by the normal entrypoint. Set `visibility.public` explicitly in the template; public listing also needs valid Factorio credentials. For rootless images, the generated file's directory must already be writable by the container UID. ### Environment Variables @@ -284,6 +288,8 @@ These are the environment variables which can be specified at container run time | Variable Name | Description | Default | Available in | |----------------------|----------------------------------------------------------------------|----------------|--------------| +| PUID | Server user ID in regular images; use `id -u` to find your host user ID | 845 | Regular images | +| PGID | Server group ID in regular images; use `id -g` to find your host group ID | 845 | Regular images | | GENERATE_NEW_SAVE | Generate a new save if one does not exist before starting the server | false | 0.17+ | | LOAD_LATEST_SAVE | Load latest when true. Otherwise load SAVE_NAME | true | 0.17+ | | PORT | UDP port the server listens on | 34197 | 0.15+ | @@ -291,10 +297,10 @@ These are the environment variables which can be specified at container run time | RCON_PORT | TCP port the rcon server listens on | 27015 | 0.15+ | | SAVE_NAME | Name to use for the save file | _autosave1 | 0.17+ | | PRESET | Map generation preset when GENERATE_NEW_SAVE is true | | 0.17+ | -| TOKEN | factorio.com token | | 0.17+ | +| TOKEN | factorio.com token for mod updates (server listing uses settings JSON) | | 0.17+ | | UPDATE_MODS_ON_START | If mods should be updated before starting the server | | 0.17+ | | UPDATE_IGNORE | Comma-separated list of mod names to skip during automatic updates | | 0.17+ | -| USERNAME | factorio.com username | | 0.17+ | +| USERNAME | factorio.com username for mod updates (server listing uses settings JSON) | | 0.17+ | | CONSOLE_LOG_LOCATION | Saves the console log to the specifies location | | | | DLC_SPACE_AGE | Enables or disables the mods for DLC Space Age in mod-list.json[^1] | true | 2.0.8+ | | MODS | Mod directory to use | /factorio/mods | 2.0.8+ | @@ -304,7 +310,13 @@ These are the environment variables which can be specified at container run time | SERVER_BANLIST_FILE | Absolute path to the server ban list | `$CONFIG/server-banlist.json` | New builds | | SERVER_WHITELIST_FILE | Absolute path to the server whitelist | `$CONFIG/server-whitelist.json` | New builds | -**Note:** All environment variables are compared as strings +**Note:** All environment variables are compared as strings. Quote YAML mapping values, for example `DLC_SPACE_AGE: "false"`. In list syntax, quote the whole item (`- "DLC_SPACE_AGE=elevated-rails"`), not only the value: `- DLC_SPACE_AGE="elevated-rails"` passes literal quotation marks to the container. + +#### Host file ownership + +The regular image starts as root, adjusts ownership inside `/factorio`, and runs the server as `PUID:PGID` (845:845 by default). To keep a bind-mounted data directory owned by your host user, set these to the numeric output of `id -u` and `id -g`. Changing them changes ownership of the mounted data, so use a dedicated directory—not your entire home directory. + +Relative bind paths such as `./data:/factorio` are convenient but do not bypass filesystem permissions. With `--user`, a rootless container engine, or a rootless image, prepare the host directory for the actual container UID/GID and any user-namespace mapping. `PUID`/`PGID` do not change identity in the rootless image; its default is 1000:1000. #### Server configuration paths @@ -360,40 +372,33 @@ The files in this volume should be owned by the factorio user, uid 845. ## Docker Compose -[Docker Compose](https://docs.docker.com/compose/install/) is an easy way to run Docker containers. - -* docker-engine >= 1.10.0 is required -* docker-compose >=1.6.0 is required - -First get a [docker-compose.yml](https://github.com/factoriotools/factorio-docker/blob/master/docker/docker-compose.yml) file. To get it from this repository: +Use the current [Docker Compose plugin](https://docs.docker.com/compose/install/) (`docker compose`) and the repository-root [docker-compose.yml](docker-compose.yml). It runs the published `factoriotools/factorio:stable` image and stores data in `./data` alongside the Compose file. No source build, `VERSION` build argument or download checksum is needed. ```shell git clone https://github.com/factoriotools/factorio-docker.git -cd factorio-docker/docker +cd factorio-docker +docker compose up -d +docker compose logs factorio +docker compose stop factorio ``` -Or make your own: +Before restarting, configure `data/config/server-settings.json`: set `visibility.public` to `false` for an unlisted server, or supply valid Factorio `username` and `token` for public listing. Set a game password or whitelist as appropriate. `USERNAME` and `TOKEN` environment variables normally configure the **mod updater**, not public listing; use the JSON file or the explicit provisioning wrapper above for server settings. See host file ownership above if you cannot edit the generated files. -```yaml -version: '2' -services: - factorio: - image: factoriotools/factorio - ports: - - "34197:34197/udp" - - "27015:27015/tcp" - volumes: - - /opt/factorio:/factorio +```shell +docker compose up -d factorio ``` -Now cd to the directory with docker-compose.yml and run: +To update, back up `data` first, then pull and recreate the service **in the same Compose directory with the same volume mapping**: ```shell -sudo mkdir -p /opt/factorio -sudo chown 845:845 /opt/factorio -sudo docker-compose up -d +docker compose pull factorio +docker compose up -d factorio ``` +The image tag selects the game version. Use `stable` for the current stable release or pin a version compatible with your clients; `latest` may be experimental. Pulling a new image alone does not replace an existing container. Do not delete the data directory during an update. + +[`docker/docker-compose.yml`](docker/docker-compose.yml) is a **developer source-build example**, not the normal installation path. Its `VERSION`, `SHA256` and optional `SHA256_ARM64` arguments verify downloaded game archives. Keep checksum verification enabled when building from source; use the published-image example if you do not want to maintain build arguments. + ### Ports * `34197/udp` - Game server (required). This can be changed with the `PORT` environment variable. @@ -460,6 +465,19 @@ stream { If your factorio host uses multiple IP addresses (very common with IPv6), you might additionally need to bind Factorio to a single IP (otherwise the UDP proxy might get confused with IP mismatches). To do that pass the `BIND` envvar to the container: `docker run --network=host -e BIND=2a02:1234::5678 ...` +### Rootless Podman networking + +For rootless Podman using **slirp4netns**, the reporter of #439 resolved incorrect address/port discovery with: + +```shell +podman run --network=slirp4netns:port_handler=slirp4netns \ + -p 34197:34197/udp \ + -v ./data:/factorio \ + factoriotools/factorio:stable +``` + +This selects the slirp4netns backend explicitly and requires it to be installed. According to [Podman's network documentation](https://docs.podman.io/en/latest/markdown/podman-run.1.html#network-mode-net), this handler preserves source IPs but is slower than the rootlesskit handler and cannot be used with user-defined networks. It is not a setting for the `pasta` backend, Docker Desktop, or your router. Host permissions, port forwarding and firewall rules still need to be correct; this workaround is not a guarantee for every NAT setup. + ## Rootless Docker Support (Experimental) > **Note**: Rootless support is currently experimental. Please report any issues you encounter. diff --git a/docker-compose.yml b/docker-compose.yml index fde22ec9..a3cb800f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,16 +1,23 @@ -version: "2" +# Normal deployment: pull the published image; no build arguments/checksums needed. services: factorio: container_name: factorio image: factoriotools/factorio:stable restart: unless-stopped + stop_grace_period: 2m ports: - "34197:34197/udp" - - "27015:27015/tcp" + # Optional remote RCON; local administration works with docker compose exec. + # - "127.0.0.1:27015:27015/tcp" volumes: - ./data:/factorio environment: - - UPDATE_MODS_ON_START=true + # Enable only after providing mod-portal credentials (see README). + - UPDATE_MODS_ON_START=false + # Optional host ownership: use the numeric output of id -u / id -g. + # - PUID=1000 + # - PGID=1000 + # - DLC_SPACE_AGE=false # Uncomment to skip updating specific mods # - UPDATE_IGNORE=mod1,mod2,mod3 @@ -21,7 +28,7 @@ services: # - com.centurylinklabs.watchtower.scope=factorio # - com.centurylinklabs.watchtower.lifecycle.pre-update="/players-online.sh" - # Uncomment the following files to use watchtower for updating the factorio container + # Uncomment the following service to use watchtower for updating the factorio container # Full documentation of watchtower: https://github.com/containrrr/watchtower #watchtower: # container_name: watchtower_factorio @@ -31,7 +38,7 @@ services: # - /var/run/docker.sock:/var/run/docker.sock # environment: # # Only update containers which have the option 'watchtower.enable=true' set - # - WATCHTOWER_TIMEOUT=30s + # - WATCHTOWER_TIMEOUT=120s # - WATCHTOWER_LABEL_ENABLE=true # - WATCHTOWER_POLL_INTERVAL=3600 # - WATCHTOWER_LIFECYCLE_HOOKS=true diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index ab04d938..2ab7e418 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,4 +1,4 @@ -version: '2' +# Developer source build. For normal deployment, use ../docker-compose.yml. services: factorio: build: @@ -14,17 +14,13 @@ services: - "27015:27015/tcp" volumes: - /opt/factorio:/factorio - # environment: - # - PUID=1000 - # - PGID=1000 - # - UPDATE_MODS_ON_START=true - # - UPDATE_IGNORE=mod1,mod2,mod3 - # - USERNAME=FactorioUsername - # - TOKEN=FactorioToken - # - PORT=34198 - # - PRESET=deathworld - # - ADDR=::1 -# # Uncomment the following line to enable the use of the host's network stack, -# # which may be necessary for some setups like NAS or when using some proxy service like firewall rules. -# extra_hosts: -# - "host.docker.internal:host-gateway" + # environment: + # PUID: "1000" + # PGID: "1000" + # UPDATE_MODS_ON_START: "true" + # UPDATE_IGNORE: "mod1,mod2,mod3" + # USERNAME: "FactorioUsername" + # TOKEN: "FactorioToken" + # PRESET: "death-world" + # BIND: "::1" + # For Linux host networking, remove ports above and set network_mode: host. diff --git a/tests/test_documented_settings.py b/tests/test_documented_settings.py new file mode 100644 index 00000000..275fd133 --- /dev/null +++ b/tests/test_documented_settings.py @@ -0,0 +1,76 @@ +"""Execute the documented JSON provisioning command without Docker or network.""" + +import json +import os +from pathlib import Path +import subprocess +import tempfile +import unittest + +ROOT = Path(__file__).resolve().parents[1] +VARIABLES = ("INSTANCE_NAME", "INSTANCE_DESC", "USERNAME", "TOKEN", "GAME_PASSWORD") + + +def example_yaml(): + text = (ROOT / "README.md").read_text() + return text.split("\n```yaml\n", 1)[1].split("```", 1)[0] + + +def example_script(): + block = example_yaml().split(" - |\n", 1)[1] + return "\n".join(line[8:] for line in block.splitlines()) + + +class DocumentedSettingsTests(unittest.TestCase): + def render(self, overrides, template=None): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + config = root / "config" + config.mkdir() + output = config / "server-settings.json" + output.write_text('{"keep":"existing settings"}') + source = root / "template.json" + source.write_text(template if template is not None else json.dumps({ + "name": "original name", "description": "original description", + "username": "original user", "token": "original token", + "game_password": "original password", "visibility": {"public": False}})) + script = example_script().replace("/factorio/config", str(config)) + script = script.replace("/server-settings.template.json", str(source)) + script = script.replace("exec /docker-entrypoint.sh", "exec /bin/true") + env = {key: value for key, value in os.environ.items() if key not in VARIABLES} + result = subprocess.run(["sh", "-ec", script], env={**env, **overrides}, + capture_output=True, text=True) + return result, json.loads(output.read_text()) + + def test_json_special_characters_are_encoded(self): + value = 'quotes " backslash \\ newline\nUnicode ü $(must-not-execute)' + result, settings = self.render(dict.fromkeys(VARIABLES, value)) + self.assertEqual(result.returncode, 0, result.stderr) + for key in ("name", "description", "username", "token", "game_password"): + self.assertEqual(settings[key], value) + self.assertEqual(settings["visibility"], {"public": False}) + + def test_unset_values_preserve_template_and_empty_values_override(self): + result, settings = self.render({"INSTANCE_NAME": "", "INSTANCE_DESC": "new"}) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(settings["name"], "") + self.assertEqual(settings["description"], "new") + self.assertEqual(settings["username"], "original user") + self.assertEqual(settings["token"], "original token") + + def test_invalid_template_preserves_existing_settings(self): + result, settings = self.render({}, template="not JSON") + self.assertNotEqual(result.returncode, 0) + self.assertEqual(settings, {"keep": "existing settings"}) + + def test_normal_compose_uses_published_image_without_build_args(self): + text = (ROOT / "docker-compose.yml").read_text() + self.assertIn("image: factoriotools/factorio:stable", text) + self.assertNotIn(" build:", text) + self.assertNotIn("SHA256=", text) + self.assertIn("stop_grace_period: 2m", text) + self.assertIn("UPDATE_MODS_ON_START=false", text) + + +if __name__ == "__main__": + unittest.main() From 417a5a14b920216fa3412c4e6f2979b691cfd7a5 Mon Sep 17 00:00:00 2001 From: Florian Kinder Date: Mon, 2 Nov 2026 19:27:08 +0100 Subject: [PATCH 2/2] Remove documentation test scaffolding and clean up README formatting --- README.md | 48 +++++++++---------- tests/test_documented_settings.py | 76 ------------------------------- 2 files changed, 24 insertions(+), 100 deletions(-) delete mode 100644 tests/test_documented_settings.py diff --git a/README.md b/README.md index fffd1e90..2ed29e3d 100644 --- a/README.md +++ b/README.md @@ -286,29 +286,29 @@ These settings variables are consumed by this example wrapper, not by the normal These are the environment variables which can be specified at container run time. -| Variable Name | Description | Default | Available in | -|----------------------|----------------------------------------------------------------------|----------------|--------------| -| PUID | Server user ID in regular images; use `id -u` to find your host user ID | 845 | Regular images | -| PGID | Server group ID in regular images; use `id -g` to find your host group ID | 845 | Regular images | -| GENERATE_NEW_SAVE | Generate a new save if one does not exist before starting the server | false | 0.17+ | -| LOAD_LATEST_SAVE | Load latest when true. Otherwise load SAVE_NAME | true | 0.17+ | -| PORT | UDP port the server listens on | 34197 | 0.15+ | -| BIND | IP address (v4 or v6) the server listens on (IP\[:PORT]) | | 0.15+ | -| RCON_PORT | TCP port the rcon server listens on | 27015 | 0.15+ | -| SAVE_NAME | Name to use for the save file | _autosave1 | 0.17+ | -| PRESET | Map generation preset when GENERATE_NEW_SAVE is true | | 0.17+ | -| TOKEN | factorio.com token for mod updates (server listing uses settings JSON) | | 0.17+ | -| UPDATE_MODS_ON_START | If mods should be updated before starting the server | | 0.17+ | -| UPDATE_IGNORE | Comma-separated list of mod names to skip during automatic updates | | 0.17+ | -| USERNAME | factorio.com username for mod updates (server listing uses settings JSON) | | 0.17+ | -| CONSOLE_LOG_LOCATION | Saves the console log to the specifies location | | | -| DLC_SPACE_AGE | Enables or disables the mods for DLC Space Age in mod-list.json[^1] | true | 2.0.8+ | -| MODS | Mod directory to use | /factorio/mods | 2.0.8+ | -| SERVER_SETTINGS_FILE | Absolute path to server settings | `$CONFIG/server-settings.json` | New builds | -| SERVER_ID_FILE | Absolute path to server identity | `$CONFIG/server-id.json` | New builds | -| SERVER_ADMINLIST_FILE | Absolute path to the server admin list | `$CONFIG/server-adminlist.json` | New builds | -| SERVER_BANLIST_FILE | Absolute path to the server ban list | `$CONFIG/server-banlist.json` | New builds | -| SERVER_WHITELIST_FILE | Absolute path to the server whitelist | `$CONFIG/server-whitelist.json` | New builds | +| Variable Name | Description | Default | Available in | +|-----------------------|---------------------------------------------------------------------------|---------------------------------|----------------| +| PUID | Server user ID in regular images; use `id -u` to find your host user ID | 845 | Regular images | +| PGID | Server group ID in regular images; use `id -g` to find your host group ID | 845 | Regular images | +| GENERATE_NEW_SAVE | Generate a new save if one does not exist before starting the server | false | 0.17+ | +| LOAD_LATEST_SAVE | Load latest when true. Otherwise load SAVE_NAME | true | 0.17+ | +| PORT | UDP port the server listens on | 34197 | 0.15+ | +| BIND | IP address (v4 or v6) the server listens on (IP\[:PORT]) | | 0.15+ | +| RCON_PORT | TCP port the rcon server listens on | 27015 | 0.15+ | +| SAVE_NAME | Name to use for the save file | _autosave1 | 0.17+ | +| PRESET | Map generation preset when GENERATE_NEW_SAVE is true | | 0.17+ | +| TOKEN | factorio.com token for mod updates (server listing uses settings JSON) | | 0.17+ | +| UPDATE_MODS_ON_START | If mods should be updated before starting the server | | 0.17+ | +| UPDATE_IGNORE | Comma-separated list of mod names to skip during automatic updates | | 0.17+ | +| USERNAME | factorio.com username for mod updates (server listing uses settings JSON) | | 0.17+ | +| CONSOLE_LOG_LOCATION | Saves the console log to the specifies location | | | +| DLC_SPACE_AGE | Enables or disables the mods for DLC Space Age in mod-list.json[^1] | true | 2.0.8+ | +| MODS | Mod directory to use | /factorio/mods | 2.0.8+ | +| SERVER_SETTINGS_FILE | Absolute path to server settings | `$CONFIG/server-settings.json` | New builds | +| SERVER_ID_FILE | Absolute path to server identity | `$CONFIG/server-id.json` | New builds | +| SERVER_ADMINLIST_FILE | Absolute path to the server admin list | `$CONFIG/server-adminlist.json` | New builds | +| SERVER_BANLIST_FILE | Absolute path to the server ban list | `$CONFIG/server-banlist.json` | New builds | +| SERVER_WHITELIST_FILE | Absolute path to the server whitelist | `$CONFIG/server-whitelist.json` | New builds | **Note:** All environment variables are compared as strings. Quote YAML mapping values, for example `DLC_SPACE_AGE: "false"`. In list syntax, quote the whole item (`- "DLC_SPACE_AGE=elevated-rails"`), not only the value: `- DLC_SPACE_AGE="elevated-rails"` passes literal quotation marks to the container. @@ -467,7 +467,7 @@ If your factorio host uses multiple IP addresses (very common with IPv6), you mi ### Rootless Podman networking -For rootless Podman using **slirp4netns**, the reporter of #439 resolved incorrect address/port discovery with: +For rootless Podman using **slirp4netns**, incorrect address or port discovery may be resolved by selecting the slirp4netns port handler: ```shell podman run --network=slirp4netns:port_handler=slirp4netns \ diff --git a/tests/test_documented_settings.py b/tests/test_documented_settings.py deleted file mode 100644 index 275fd133..00000000 --- a/tests/test_documented_settings.py +++ /dev/null @@ -1,76 +0,0 @@ -"""Execute the documented JSON provisioning command without Docker or network.""" - -import json -import os -from pathlib import Path -import subprocess -import tempfile -import unittest - -ROOT = Path(__file__).resolve().parents[1] -VARIABLES = ("INSTANCE_NAME", "INSTANCE_DESC", "USERNAME", "TOKEN", "GAME_PASSWORD") - - -def example_yaml(): - text = (ROOT / "README.md").read_text() - return text.split("\n```yaml\n", 1)[1].split("```", 1)[0] - - -def example_script(): - block = example_yaml().split(" - |\n", 1)[1] - return "\n".join(line[8:] for line in block.splitlines()) - - -class DocumentedSettingsTests(unittest.TestCase): - def render(self, overrides, template=None): - with tempfile.TemporaryDirectory() as directory: - root = Path(directory) - config = root / "config" - config.mkdir() - output = config / "server-settings.json" - output.write_text('{"keep":"existing settings"}') - source = root / "template.json" - source.write_text(template if template is not None else json.dumps({ - "name": "original name", "description": "original description", - "username": "original user", "token": "original token", - "game_password": "original password", "visibility": {"public": False}})) - script = example_script().replace("/factorio/config", str(config)) - script = script.replace("/server-settings.template.json", str(source)) - script = script.replace("exec /docker-entrypoint.sh", "exec /bin/true") - env = {key: value for key, value in os.environ.items() if key not in VARIABLES} - result = subprocess.run(["sh", "-ec", script], env={**env, **overrides}, - capture_output=True, text=True) - return result, json.loads(output.read_text()) - - def test_json_special_characters_are_encoded(self): - value = 'quotes " backslash \\ newline\nUnicode ü $(must-not-execute)' - result, settings = self.render(dict.fromkeys(VARIABLES, value)) - self.assertEqual(result.returncode, 0, result.stderr) - for key in ("name", "description", "username", "token", "game_password"): - self.assertEqual(settings[key], value) - self.assertEqual(settings["visibility"], {"public": False}) - - def test_unset_values_preserve_template_and_empty_values_override(self): - result, settings = self.render({"INSTANCE_NAME": "", "INSTANCE_DESC": "new"}) - self.assertEqual(result.returncode, 0, result.stderr) - self.assertEqual(settings["name"], "") - self.assertEqual(settings["description"], "new") - self.assertEqual(settings["username"], "original user") - self.assertEqual(settings["token"], "original token") - - def test_invalid_template_preserves_existing_settings(self): - result, settings = self.render({}, template="not JSON") - self.assertNotEqual(result.returncode, 0) - self.assertEqual(settings, {"keep": "existing settings"}) - - def test_normal_compose_uses_published_image_without_build_args(self): - text = (ROOT / "docker-compose.yml").read_text() - self.assertIn("image: factoriotools/factorio:stable", text) - self.assertNotIn(" build:", text) - self.assertNotIn("SHA256=", text) - self.assertIn("stop_grace_period: 2m", text) - self.assertIn("UPDATE_MODS_ON_START=false", text) - - -if __name__ == "__main__": - unittest.main()