diff --git a/README.md b/README.md index 83f35ae4..2ed29e3d 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,58 +244,79 @@ 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 These are the environment variables which can be specified at container run time. -| Variable Name | Description | Default | Available in | -|----------------------|----------------------------------------------------------------------|----------------|--------------| -| 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 | | 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+ | -| 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 +| 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. + +#### 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**, incorrect address or port discovery may be resolved by selecting the slirp4netns port handler: + +```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.