factorio/README.md

Factorio team server chart

This repository maintains a portable Helm chart for the upstream Factorio dedicated-server image. The chart includes the single-server Deployment, services, persistent-data contract, runtime configuration, probes, player collector, node-exporter textfile metrics, ServiceMonitor, Prometheus alerts, and Grafana dashboard. It does not build or publish a custom game image.

The homelab deployment's cluster-specific values are maintained separately in homelab-gitops.

The chart defaults to the Factorio release in Chart.yaml.appVersion; the player collector uses the same release. The node-exporter image is independently selected in values.yaml. Site-specific IPs, router annotations, node placement, storage claim, dashboard namespace, and cluster sizing belong in the consumer's values file. This repository contains no homelab addresses or hostnames.

Use the published chart

helm repo add brunner.ninja https://brunner.ninja/charts
helm repo update brunner.ninja
helm upgrade --install factorio brunner.ninja/factorio \
  --namespace factorio --create-namespace --wait --timeout 30m \
  --set persistence.size=16Gi

The default chart creates a PVC. To adopt an existing claim, set persistence.existingClaim to its name. Supply your own Service annotations, external IPs, resources, affinity, tolerations, and dashboard location through values; these settings are intentionally not baked into the chart defaults.

RCON credentials are read from an existing Secret named by credentials.secretName (default factorio-runtime). The chart never creates or stores the password. The Secret must contain the rcon-password key.

Upgrade Factorio yourself

For an application release such as 2.1.23:

1. Set appVersion in Chart.yaml to 2.1.23. Do not edit version; CI derives the chart package version from Git tags with git describe --tags --long.
2. Run ./test.sh, inspect the diff, and commit the change to main.
3. Tag that commit with the exact application version, for example git tag v2.1.23, then push the commit and tag with git push origin main v2.1.23.
4. Gitea Actions validates and publishes the chart to the public indexed Helm repository, then updates only Factorio's chart targetRevision in homelab-gitops. Argo CD applies the new release; no manual GitOps edit or Kubernetes credential is needed.

The chart version at an application tag is the application version. A later chart-only commit becomes a unique git describe version such as 2.1.23-1-g41627abcdef. GitOps selects the exact promoted chart version.

Data and runtime behavior

One replica and a Recreate strategy prevent overlapping game servers on the same world. Shutdown requests a save and allows 180 seconds. Startup snapshots existing save ZIPs into upgrade-backups/ on the same PVC before the new binary loads them, retaining five snapshots. These snapshots help with game-version rollback but are not an off-volume backup. Older Factorio binaries may not load a save converted by a newer release, so restore a matching snapshot before rolling back.

The readiness and startup probes check authenticated RCON and writable save storage. Liveness allows time for long saves. The player collector uses only /players online to preserve achievements; failed RCON queries omit player counts and report the server as unavailable. RCON is not exposed by either Service.

Test and local install

./test.sh
FACTORIO_SMOKE_TEST=true ./test.sh  # uses Podman to boot the actual image
./install.sh --values /path/to/your-values.yaml