factorio-docker/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Docker image for running a Factorio headless server. It provides automated builds for multiple Factorio versions (stable and experimental) and supports both AMD64 and ARM64 architectures.

Architecture

Key Components

1. Docker Image Build System

   • build.py - Unified Python script that builds both regular and rootless Docker images from buildinfo.json
   • docker/Dockerfile - Main Dockerfile that creates the Factorio server image
   • docker/Dockerfile.rootless - Dockerfile for rootless variant (runs as UID 1000)
   • buildinfo.json - Contains version info, SHA256 checksums, and tags for all supported versions
   • Supports multi-architecture builds (linux/amd64, linux/arm64) using Docker buildx

2. Automated Updates

   • update.sh - Checks for new Factorio releases and updates buildinfo.json
   • Updates README.md with new version tags
   • Commits changes and tags releases automatically
   • Run by GitHub Actions to keep images up-to-date

3. Container Scripts

   • docker/files/docker-entrypoint.sh - Main entrypoint that configures and starts the server
   • docker/files/docker-update-mods.sh - Updates mods on server start
   • docker/files/docker-dlc.sh - Manages DLC (Space Age) activation
   • docker/files/scenario.sh - Alternative entrypoint for launching scenarios
   • docker/files/players-online.sh - Checks if players are online (for watchtower integration)

4. RCON Client

   • docker/rcon/ - C source for RCON client, built during Docker image creation
   • Allows sending commands to the running server

Common Development Commands

Building Images

# Build regular images locally (single architecture)
python3 build.py

# Build rootless images only
python3 build.py --rootless

# Build both regular and rootless images
python3 build.py --both

# Build and push multi-architecture images (regular only)
python3 build.py --multiarch --push-tags

# Build and push both regular and rootless multi-architecture images
python3 build.py --multiarch --push-tags --both

Running the Container

# Basic run command
docker run -d \
  -p 34197:34197/udp \
  -p 27015:27015/tcp \
  -v /opt/factorio:/factorio \
  --name factorio \
  factoriotools/factorio

# Using docker-compose
docker-compose up -d

Linting

# Lint Dockerfiles
./lint.sh

Testing Updates

# Check for new Factorio versions and update buildinfo.json
./update.sh

Key Configuration

Environment Variables

• LOAD_LATEST_SAVE - Load the most recent save (default: true)
• GENERATE_NEW_SAVE - Generate a new save if none exists (default: false)
• SAVE_NAME - Name of the save file to load/create
• UPDATE_MODS_ON_START - Update mods before starting (requires USERNAME/TOKEN)
• DLC_SPACE_AGE - Enable/disable Space Age DLC (default: true)
• PORT - UDP port for game server (default: 34197)
• RCON_PORT - TCP port for RCON (default: 27015)

Volume Structure

All data is stored in a single volume mounted at /factorio:

/factorio/
├── config/           # Server configuration files
├── mods/            # Game modifications
├── saves/           # Save games
├── scenarios/       # Scenario files
└── script-output/   # Script output directory

Version Management

The project maintains compatibility with multiple Factorio versions:

• Latest experimental version gets the latest tag
• Latest stable version gets the stable tag
• Each version also gets specific tags (e.g., 2.0.55, 2.0, 2)
• Legacy versions back to 0.12 are supported

Version updates are automated via GitHub Actions that run update.sh periodically.

Testing Changes

1. Modify buildinfo.json to test specific versions
2. Run python3 build.py to build regular images locally
   • Use python3 build.py --rootless for rootless images
   • Use python3 build.py --both to build both variants
3. Test the container with your local data volume
4. For production changes, ensure update.sh handles version transitions correctly