/Factorio-Container

Another Docker container for Factorio servers.

Primary LanguagePythonMIT LicenseMIT

Factorio Container

A Docker container for running headless Factorio servers.

Currently the project supports the following ways of running the container:

Quickstart

The fastest way to get up and running is using Docker Compose.

Simply follow these instructions:

  1. Clone this repository (Alternately you can download the docker-compose.yaml file directly).
  2. Create a copy of the .env.example file, and name it .env.
  3. Fill in the FACTORIO_SAVE_FILE and FACTORIO_WHITELIST variables.
  4. Run docker-compose up and subsequently docker-compose down (This generates the neccesary directory structure in the FACTORIO_DATA_DIRECTORY directory. ~/factorio by default).
  5. Place your save file inside FACTORIO_DATA_DIRECTORY/saves.
  6. Run docker-compose up -d. That's it, your factorio server is now running.

Supported Features

This container is by no means a completed and polished product. Although it can run a Factorio server just fine, there are other things it cannot (yet) do.

Below is a list of the features that are supported, and planned in the near future.

  • Factorio
    • Whitelisting on / off.
    • Running an existing map (Note: Using the container to generate a new map is currently not supported. You must provide a map for the server to load).
    • Playing with mods (The server does not do anything to update / install mods, you must install the mods into the server's data directory).
    • Generating default config files.
    • Variable version support (Factorio version is specificed by build parameter to Dockerfile).
  • Docker
    • Compose.
    • Volume mounting for permanent storage.
    • Pulling the container from Docker Hub.
    • Running as a non-root user.
  • Docker Compose
    • Defining volume as environment variable.
    • Defining factorio version as environment variable.

For the in-depth details of how the container works, and what you can do, keep reading.

Docker Compose

The Docker Compose file is the recommneded way to run the container on a single host, where you're planning on using local storage for the server.

Docker Compose takes care of pulling down / building the container as needed, creating the required volume from a local directory, binding the appropriate port, and starting the container.

The only peice of configuration required is found in the .env.example file. First you should create a copy of this file, and name it .env Note: The file must be named .env for Docker Compose to use it to populate the required variables.

See the content of .env.example for a list of supported variables.

Docker

If you wish to run the container directly (Perhaps you don't wish to use a local volume driver), that's also an option, albeit a bit more involved.

Pre-requisits

Note: The container requires a save file be provided for the server to run. It does not support generating the map in the container at this time.

Besides the standard requirements for running a Docker container, this container requires a volume be configured.

The required directories within the volume will automatically be generated by the container during startup in the entrypoint.py script.

If you wish to configure the directories yourself, you may do so follwing the instructions outlined by Volume Format.

Usage

Running the container requires two sets of arguments. Those used by docker to run the container, and those used by the container to start the factorio server.

They are combined in the format: docker run [container arguments] factorio-container [entrypoint arguments].

An example of a full command would be:

docker run -p 34197:34197/udp --mount source=myvol,target=/mnt/factorio factorio-container --whitelist -s mysave.zip

Container Arguments

The container itself takes two arguments to run, the port to expose the server on, and the volume to store the files on.

  • Port: You'll need to bind 34197/udp on the container, in most cases you'll wish to do so to the same port on the host (With -p 34197:34197/udp), as it's the default port used by Factorio.
  • Volume: As discussed the container needs a volume bound to /mnt/factorio for config, mod, and save file storage. (Eg. --mount source=myvol,target=/mnt/factorio)

Entrypoint Arguments

The entrypoint takes two more arguments, which are used in starting the factorio server binary.

  • -s / --save-file: The name of the save file to use. This file must be stored within the saves/ directory on the volume. (Eg. mysave.zip)
  • --whitelist / --no-whitelist: Used to indicate if this should be a server gated with a whitelist of players, or not.

Building

It is possible to build the container from scratch, if you wish to do so. The Dockerfile takes exactly one build argument: VERSION. This argument is used to specify which version of Factorio the container should be built for. By default stable is used.

See https://factorio.com/download-headless for valid values of this parameter.

Examples:

  • docker build . - Builds a container for Factorio stable
  • docker build --build-arg VERSION=latest . - Builds a container for Factorio's latest experimental version
  • docker build --build-arg VERSION=0.18.18 .- Builds a container for Factorio version 0.18.18

Volume Format

The volume must contain the following file tree:

  • config
    • map-gen-settings.json
    • map-settings.json
    • server-settings.json
    • server-adminlist.json (Automatically generated when the first player is promoted)
    • server-banlist.json (Automatically generated when the first player is banned)
    • server-whitelist.json (Only used with the --whitelist flag)
  • mods
    • [any mods you wish to use]
  • saves
    • [one or more save files]

All of the directories and files must have read, write, and execute permission for a user with UID 1000, and GID 1000. (This is because the factorio user inside the container needs the ability to interact with these files, without using root permissions)

On a Unix-like system, this can be achieved by running the following commands inside the volume:

chown -R 1000:1000 .
chmod -R u+rwx .

I'd like to thank the factoriotools team for inspiring me to try my hand at containerizing Factorio.