mirror of
https://github.com/factoriotools/factorio-docker.git
synced 2025-07-12 20:15:35 +02:00
- Project overview and architecture description - Common development commands for building and testing - Environment variables and configuration details - Version management and automated update process - Volume structure and data organization 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
3.6 KiB
3.6 KiB
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
-
Docker Image Build System
build.py
- Python script that builds Docker images frombuildinfo.json
docker/Dockerfile
- Main Dockerfile that creates the Factorio server imagebuildinfo.json
- Contains version info, SHA256 checksums, and tags for all supported versions- Supports multi-architecture builds (linux/amd64, linux/arm64) using Docker buildx
-
Automated Updates
update.sh
- Checks for new Factorio releases and updatesbuildinfo.json
- Updates README.md with new version tags
- Commits changes and tags releases automatically
- Run by GitHub Actions to keep images up-to-date
-
Container Scripts
docker/files/docker-entrypoint.sh
- Main entrypoint that configures and starts the serverdocker/files/docker-update-mods.sh
- Updates mods on server startdocker/files/docker-dlc.sh
- Manages DLC (Space Age) activationdocker/files/scenario.sh
- Alternative entrypoint for launching scenariosdocker/files/players-online.sh
- Checks if players are online (for watchtower integration)
-
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 a single architecture image locally
python3 build.py
# Build and push multi-architecture images
python3 build.py --multiarch --push-tags
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/createUPDATE_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
- Modify
buildinfo.json
to test specific versions - Run
python3 build.py
to build locally - Test the container with your local data volume
- For production changes, ensure
update.sh
handles version transitions correctly