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](https://code.brunner.ninja/feedc0de/homelab-gitops/src/branch/main/apps/factorio/values.yaml).

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

```sh
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

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