Overview

Date: 2026-05-11

Time: 15:23

Overview

ftl2-servercraft is a full application built on FTL2 that manages game server lifecycles (Minecraft NeoForge and Terraria) on Linode infrastructure. It demonstrates FTL2 used not as a one-off automation tool but as the infrastructure layer for a complete application with a TUI dashboard, background watchdog, backup/restore, and automatic idle teardown.

Key Concepts

• FTL2 as application infrastructure: Servercraft uses FTL2's automation() context manager as its sole mechanism for remote operations — provisioning, monitoring, backup, and teardown all flow through FTL2 module calls over SSH.
• Script interface pattern: Each game type is a Python module implementing a standard contract (provision, startserver, verifyserver, restoreworld, backupworld, getplayercount, saveandstop, destroy), loaded dynamically via get_script(name).
• Host groups map to inventory: Terraria operations use ftl.terraria.*, NeoForge uses ftl.minecraft.* — these are Ansible inventory groups, showing how FTL2 inventory groups organize multi-service automation.
• Secret bindings: Environment variables (LINODETOKEN, SLACKTOKEN) are mapped to module parameters via secret_bindings in the automation context, demonstrating FTL2's secret management without Vault.
• Watchdog pattern: A polling loop that uses FTL2 to check player counts, track idle time, and trigger automated backup + teardown — showing FTL2 in a long-running daemon context.
• State files: Track provisioned Linode instances (IP, ID, label), demonstrating FTL2's state persistence across runs.
• tmux-based server management: Game servers run in tmux sessions on remote hosts; all monitoring and control happens through tmux commands executed via FTL2 shell modules.

Commands and Syntax

# FTL2 automation context — the core pattern
async with automation(...) as ftl:
    # Module access via attribute chains (group.module)
    ftl.minecraft.shell(cmd="...")
    ftl.terraria.dnf(name="...")

# Secret bindings in automation context
async with automation(
    secret_bindings={"LINODE_TOKEN": ..., "SLACK_TOKEN": ...}
) as ftl:
    ...

# CLI entry points
ftl2-servercraft            # Run the TUI
ftl2-servercraft status     # Check status without TUI
ftl2-servercraft --config my-servers.yml  # Custom config

# Development install
uv pip install -e .

# servers.yml structure
# Each entry specifies: script type, config_dir, and server params
# script: <game> maps to ftl2_servercraft/scripts/<game>.py

Relationships

• Inventory management: Host groups (terraria, minecraft) are used to target operations, showing real-world inventory group usage.
• Module usage: Attribute-chain module calls (ftl.group.module(params)) are the primary API surface for all remote operations.
• Secret bindings: Demonstrates the secret_bindings parameter of automation() as an alternative to full Vault integration for environment-variable-based secrets.
• State & idempotency: State files track provisioned resources, enabling crash recovery and preventing duplicate provisioning.
• Error handling: Watchdog handles consecutive connection failures (3+ = server down), showing FTL2 error handling in production.
• Building applications: Primary example of FTL2 as an application framework rather than a scripting tool — TUI + watchdog + background threads all driving FTL2 automation contexts.

Exam-Relevant Points

• The automation() context manager is the entry point for all FTL2 remote operations — used with async with.
• Module calls follow the pattern ftl.<inventorygroup>.<modulename>(param=value).
• secret_bindings maps environment variables to module parameters without requiring Vault.
• FTL2 can run in long-lived application contexts (watchdog daemon), not just one-shot scripts.
• Host groups in FTL2 correspond to Ansible inventory groups and determine which hosts receive module calls.
• Backup paths differ by game type — the application must handle game-specific filesystem layouts.
• Adding a new automation target requires: implementing the script interface, adding config, and updating backup logic — showing FTL2's extensibility pattern.