Files
factorio-docker/CLAUDE.md
Florian Kinder 8784845385 Add CLAUDE.md with project guidance for Claude Code
- 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>
2025-07-03 19:22:52 +09:00

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

  1. Docker Image Build System

    • build.py - Python script that builds Docker images from buildinfo.json
    • docker/Dockerfile - Main Dockerfile that creates the Factorio server image
    • 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 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/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 locally
  3. Test the container with your local data volume
  4. For production changes, ensure update.sh handles version transitions correctly