release: docs/TODO.md + networking docs + readme expansion #2

Merged

Sponge merged 3 commits from develop into main

2026-05-25 06:00:53 +00:00

Sponge commented

2026-05-25 06:00:45 +00:00

Owner

Summary

Promotes docs work from develop to main. Two commits land on main:

b34f73e — docs: capture #1 #2 #3 bootstrap bugs in docs/TODO.md
9f2d75f — docs: expand networking docs (README + docs/networking.md + UserEngine.ini.example)
5e7e3e4 (merge commit) — PR #1 from feature/bootstrap-fixes into develop

Why this is release-worthy

100% docs, zero code change to ubuntu-scripts/ — no functional regression risk
Generalized NAT findings (no personal-host details leak into public material)
Captures the bootstrap bugs publicly so anyone hitting them sees a coherent diagnosis

Test plan

Public Forgejo URL https://git.unityailab.com/Sponge/Dune-Awakening-Server-Tools renders the new docs (README sections + docs/networking.md + UserEngine.ini.example)
No personal/private details in any docs/* or ubuntu-scripts/* file (Sponge's specific Starlink topology stays in CLAUDE.md only, which is gitignored)
LICENSE + README disclaimer chain intact

## Summary Promotes docs work from develop to main. Two commits land on main: - **b34f73e** — docs: capture #1 #2 #3 bootstrap bugs in docs/TODO.md - **9f2d75f** — docs: expand networking docs (README + docs/networking.md + UserEngine.ini.example) - **5e7e3e4** (merge commit) — PR #1 from feature/bootstrap-fixes into develop ## Why this is release-worthy - 100% docs, zero code change to ubuntu-scripts/ — no functional regression risk - Generalized NAT findings (no personal-host details leak into public material) - Captures the bootstrap bugs publicly so anyone hitting them sees a coherent diagnosis ## Test plan - [x] Public Forgejo URL <https://git.unityailab.com/Sponge/Dune-Awakening-Server-Tools> renders the new docs (README sections + docs/networking.md + UserEngine.ini.example) - [x] No personal/private details in any docs/* or ubuntu-scripts/* file (Sponge's specific Starlink topology stays in CLAUDE.md only, which is gitignored) - [x] LICENSE + README disclaimer chain intact

Sponge added 3 commits

2026-05-25 06:00:45 +00:00

docs: capture #1 #2 #3 bootstrap bugs from first end-to-end world test b34f73e859

Three real bugs surfaced during the first end-to-end world-creation test
on the Multipass dune-test VM (Ubuntu 24.04 + k3s, world
sh-9e14edb5d4003e4b-qmqtjz, "Dune Test — Multipass VM"). The bootstrap
got us to operators-Running and the world up to PHASE=Running with both
Survival_1 + Overmap game servers serving — but only after working around
#1 with a live kubectl patch.

User directive (verbatim, 2026-05-24): "make a feature branch, and start
dealing with #1 #2 and #3, although... pause on the 1 2 and 3 right this
second, do the stage commit push and feature branch now".

This commit creates docs/TODO.md and captures the three bugs as pending
entries on feature/bootstrap-fixes so the branch has a clear ledger to
work against when work resumes:

  #1 BLOCKER memory-focused-scheduler missing from bootstrap. Funcom's
  world-template.yaml references this custom scheduler on every game-server
  set (30+ refs) but their Alpine VHDX must pre-deploy it — ours doesn't.
  Game-server pods sit Pending forever with zero scheduling events because
  the default kube-scheduler ignores them. Worked around live with a
  kubectl patch rewriting every set's schedulerName to default-scheduler.
  Three fix paths captured (deploy the scheduler / sed-strip in world.sh /
  runtime kubectl patch post-apply); recommend deploying the scheduler.

  #2 LOW enable-experimental-swap k3s-restart-induced BackOff churn.
  setup/experimental_swap.sh:restart_k3s_after_swap() restarts k3s + sleeps
  120s, but in-namespace dependents (director, gateway, text-router) come
  up before Postgres is ready and crash-loop with Connection refused until
  BackOff settles. Fix: kubectl-wait for DB Ready before returning.

  #3 NIT db-dbdepl-util parallel-init race — two jobs both CREATE DATABASE
  dune, one wins, one gets UniqueViolation and lands in Error. Functionally
  harmless (migrations complete via the winning job). Funcom design — leave
  open, monitor across Funcom build updates.

Work paused per user directive — picking up router questions next.

docs: expand networking docs from end-to-end LAN test findings 9f2d75f844

Surfaces all publicly-useful learnings from the first end-to-end world test
on the Multipass dune-test VM (Ubuntu 24.04 + k3s), generalized to a
universal "what does my topology need?" reference. No personal-host details
(no specific WAN IPs, no specific HostIds, no ISP-specific findings).

User directive (verbatim, 2026-05-24): "How much of it is 'dont mention we
did this' and how much is 'this is super helpful to others' that we can
document for the ubuntu setup process? Cause this SHOULD work bare metal,
but we are using an ubuntu VM, which either way, that much I know we
should document."

Changes:

* ubuntu-scripts/README.md — three new troubleshooting subsections:
  - "Network topology — bare-metal vs VM" — explains why VM-based installs
    need iptables DNAT (game pods use hostNetwork:true and bind to the
    VM's bridge IP, not the host's LAN IP). Includes the working iptables
    rule pattern + the persistence step.
  - "NAT options — choosing your reachability path" — matrix covering
    real-public-IPv4 / single-NAT / double-NAT / CGNAT / LAN-only, with
    detection commands and recommended fix per case. Links to
    docs/networking.md for deeper detail.
  - "kubectl apply -f /home/dune/.dune/sh-*.yaml resets your world" —
    the rendered spec ships image tags as 0-0-shipping placeholder, so
    re-applying it after update-from-downloads or kubectl patch operations
    overwrites the live-patched state. Treat the rendered YAML as a seed,
    not the live source of truth.

* docs/networking.md (NEW) — the deep design doc:
  - How HOST_DATACENTER_IP_ADDRESS announces work
  - Game-server port architecture (UDP 7777-7889 + TCP 31982)
  - Bare-metal vs VM topology with ASCII diagrams
  - Full iptables DNAT pattern for VM installs
  - NAT-piercing options for every common residential topology
    (single-NAT, double-NAT, CGNAT, LAN-only) with concrete commands
  - Tunnel-service options (Playit.gg, Tailscale Funnel, Cloudflare
    Spectrum, self-hosted WireGuard)
  - Diagnostic commands (ss listener check, tcpdump on WAN, director
    log search, iptables counter check)
  - Common failure-mode lookup table

* ubuntu-scripts/examples/UserEngine.ini.example (NEW) — annotated example
  CVar overrides anyone can use as a starting point. Includes:
  - Sandworm tuning block
  - Sandstorm + treasure
  - World-border kill-mechanisms DISABLED (Hazard.EnableQuicksandOnIGWBorders,
    Vehicle.LevelBorders*) — for friend-server sandbox use
  - Resource yield multipliers (commented out, pointing to Funcom defaults)
  - Vehicle fuel multiplier (dw.VehiclePowerConsumptionMultiplier=0)
    flagged with the "this is Funcom-internal dw.* namespace, verify on
    your build" caveat
  - Player-death loot toggle (commented out, for PvE-friendly configs)

Personal-host details (specific WAN/HostId/ISP topology) deliberately
kept out — those stayed in the session conversation and are not part of
the public release.

Merge pull request 'docs: bootstrap bugs + networking docs from end-to-end LAN test' (#1 ) from feature/bootstrap-fixes into develop 5e7e3e4f49