Overview

Date: 2026-05-11

Time: 15:24

Overview

ftl2-servercraft is a full application built on FTL2 that manages game server lifecycles (Minecraft and Terraria) on Linode infrastructure. It demonstrates FTL2's use as an application infrastructure layer rather than just a scripting tool, combining provisioning automation with a live Textual TUI dashboard and automated watchdog teardown of idle servers.

Key Concepts

• FTL2 as application infrastructure — ftl2-servercraft is not a one-off script; it's a persistent application that uses FTL2 for all infrastructure operations (provisioning, backup, teardown)
• Script interface contract — each game type (neoforge, terraria) implements a standard set of functions (provision, startserver, verifyserver, backupworld, getplayercount, saveand_stop, destroy), all receiving an ftl object as first parameter
• Watchdog pattern — polls player count at configurable intervals, triggers auto-teardown (backup + destroy) after a grace period of zero players
• Post-start verification — checks that the game's tmux session actually survived startup before reporting success; guards against silent failures
• Configuration-driven servers — all server definitions live in servers.yml with per-server settings for game type, Linode sizing, DDNS, grace periods, and external config directories
• Separation of game config from app config — game-specific files (server.properties, run.sh) live in a separate config_dir, not inline

Commands and Syntax

Installation and launch:

uv pip install -e .
cp servers.yml.example servers.yml
ftl2-servercraft

Server definition (servers.yml):

servers:
  minecraft-1:
    label: "World 1 (NeoForge)"
    script: neoforge            # selects scripts/neoforge.py
    admin_user: admin
    world_name: world
    linode_type: g6-standard-1
    linode_region: us-east
    config_dir: ~/git/server-configs/minecraft-world-1
    ddns_hostname: world1.example.com
    grace_period: 300           # seconds before idle teardown
    poll_interval: 30           # seconds between player count checks

TUI keybindings: L (launch), R (reconfigure), V (verify), B (backup), S (stop+destroy), W (toggle watchdog), Q (quit)

Required environment variables: LINODETOKEN, LINODEROOTPASS, SLACKTOKEN

Relationships

• FTL2 core — all provisioning calls go through the ftl object passed to script functions; this is the primary consumer example of FTL2's automation API
• Inventory management — Linode instances are dynamically provisioned, demonstrating FTL2's dynamic host handling rather than static YAML inventory
• Module usage — provisioning scripts call FTL2 modules for SSH setup, firewall config, package installation, file transfer (backup/restore)
• Error handling — verify_server pattern shows FTL2's approach to post-action validation
• Vault integration — environment variables (LINODETOKEN, LINODEROOT_PASS) are candidates for Vault secret bindings in production
• Real-world deployments — serves as a reference implementation alongside ftl2-deployments for how to structure FTL2-based applications

Exam-Relevant Points

• The ftl object is passed as the first argument to all script interface functions — this is the primary handle for FTL2 automation operations within an application
• The script interface defines exactly 8 functions: provision, startserver, verifyserver, restoreworld, backupworld, getplayercount, saveandstop, destroy
• verifyserver returns bool; getplayer_count returns int | None — the None case must be handled (server unreachable vs zero players)
• Grace period and poll interval are per-server configuration, not global settings
• The script field in servers.yml selects which Python module under scripts/ handles that server type
• FTL2 can be used as an infrastructure layer for persistent applications with TUIs, not just for one-off automation scripts
• Provisioning is idempotent enough to support "Reconfigure" (re-run on existing server) as a distinct operation from initial "Launch"