Overview

Date: 2026-05-11

Time: 15:55

Overview

This is a Textual-based terminal UI (TUI) dashboard for ftl2-servercraft, a Minecraft server lifecycle manager. It provides a real-time dashboard showing server status, player counts, watchdog state, and grace-period countdowns. Users can launch, stop, backup, verify, and reconfigure Minecraft servers through keyboard shortcuts, with all heavy operations (provisioning, teardown, backup) running in background threads while the UI remains responsive. The TUI uses FTL2's automation context manager to execute infrastructure scripts against Linode cloud instances.

Usage Patterns

The app is instantiated with a config file path and run as a Textual application:

app = ServerCraftApp(config_path="servers.yaml")
app.run()

Key keyboard bindings drive the interface:

• L — Launch a server (shows modal to choose restore-from-backup or fresh)
• S — Stop a server (confirmation modal, then backup + destroy)
• W — Toggle watchdog (auto-teardown when server is empty)
• B — Backup world without stopping
• V — Verify server is alive (checks tmux session)
• R — Reconfigure a running server (re-provision without destroy)
• Enter — Open detail view for selected server
• Q — Quit (stops all watchdogs first)

All operations select the currently highlighted row in the DataTable.

API and Configuration

Config inputs:

• ServerConfig objects loaded via loadconfig(configpath) — each defines: name, label, script, worldname, linodetype, linoderegion, graceperiod, pollinterval, statefile, inventorypath, minecraftversion, ddnshostname, slackchannel
• Config also provides getbackups(), isprovisioned(), get_ip() methods

FTL2 automation parameters (used in every operation):

• secretbindings — maps module FQCNs to Vault secret names (LINODETOKEN, LINODEROOTPASS, SLACK_TOKEN)
• inventory — path from config
• state_file — path from config for crash recovery
• failfast=True, autoinstall_deps=True
• gate_modules="auto" — used only during provisioning for performance

Logging: Provisioning writes to logs/provision-{name}-{timestamp}.log in addition to the TUI activity log.

Key Behaviors

• Thread-based concurrency: All FTL2 operations run in daemon threads with their own asyncio event loops. The TUI timer refreshes the dashboard every 2 seconds by reading shared runtime_state.
• Shared mutable state: runtime_state is a module-level dict of ServerState dataclasses, written by background threads and read by the TUI. No locking — relies on GIL and simple attribute writes.
• Watchdog grace period: When a server has zero players, emptysince tracks the timestamp. The dashboard shows a countdown; the watchdog (in watchdog.py) handles the actual teardown after graceperiod seconds.
• Provisioning flow: Provision → optionally restore backup → start server → verify → auto-enable watchdog. If verification fails, status goes to error.
• Stop flow: Disable watchdog → set status to stopping → save & stop server → backup world → notify Slack → destroy Linode. Backup failure is caught but doesn't abort teardown.
• State detection on startup: checkexisting_state() reads state files to detect already-provisioned servers, so the dashboard reflects reality on restart.
• Modal screens: Launch and stop use dismissable modal screens (ModalScreen) that return values via callbacks. The provisioning screen can be escaped without canceling the operation.
• Duplicate prevention: Backup tracks active operations via backupactive set; provisioning checks status before allowing re-launch.

Relationships

• Imports from package: .config.ServerConfig and .config.loadconfig for server definitions; .watchdog.runwatchdog for the player-monitoring loop; .scripts.get_script() for server-type-specific operations (provision, start, stop, backup, verify, restore, destroy)
• FTL2 dependency: Uses ftl2.automation as an async context manager — the core interface for running infrastructure modules
• Modules used via FTL2: community.general.linode_v4 (Linode provisioning), community.general.slack (notifications)
• External services: Linode API (server lifecycle), HashiCorp Vault (secrets via secret_bindings), Slack (stop notifications)
• UI framework: Built on Textual (with Rich for text styling), using Screen, ModalScreen, DataTable, RichLog, Header, Button, Label widgets