Overview

Date: 2026-05-11

Time: 15:11

Overview

This page describes a deployment plan for ftl2-stargate, a web application, on a Linode VPS. The architecture uses Cloudflare for DNS (non-proxied), Caddy as a reverse proxy with automatic Let's Encrypt TLS, and systemd for service management. The deployment is incremental: provision infrastructure, configure DNS, set up the reverse proxy, install applications, and verify.

Key Concepts

• ftl2-stargate is a web application that listens on port 8000 (plain HTTP) and requires Google OAuth for authentication.
• Caddy handles TLS termination automatically via Let's Encrypt, reverse-proxying HTTPS :443 to the app on :8000.
• Cloudflare DNS is used in DNS-only mode (no orange cloud/proxy) so Caddy can perform its own ACME HTTP challenge on port 80.
• textual-serve wraps a Textual TUI app (ftl2-htop) as a web-accessible service on port 8002.
• The Linode is provisioned from a pre-baked private image (private/37121878, stargate-fedora43) that includes Caddy, Python, and common packages.
• Secrets (Google OAuth credentials, secret key, allowed emails) are not automated — they are entered interactively at startup.

Commands and Syntax

Caddyfile (/etc/caddy/Caddyfile):

stargate.catbeez18.com {
    reverse_proxy localhost:8000
}

Application installation:

pip install uv
pip install "ftl2-stargate @ git+https://github.com/benthomasson/ftl2-stargate"
pip install "ftl2-htop @ git+https://github.com/benthomasson/ftl2-htop"
pip install textual-serve

textual-serve systemd command:

textual serve -c "ftl2-htop -i inventory.yml" --port 8002

Linode provisioning parameters: image private/37121878, type g6-standard-1, region us-east.

Cloudflare DNS: A record, DNS-only (not proxied), using CLOUDFLAREAPITOKEN env var.

Firewall: Ports 80 (ACME challenge) and 443 (HTTPS) must be opened.

SSH hardening: Disable password auth, IPv4 only, admin user with SSH key.

Relationships

• Cloudflare integration — uses the Cloudflare API for DNS record creation; mirrors patterns from other ftl2 deployments (e.g., ftl2-servercraft's Cloudflare DNS module).
• Inventory files — ftl2-htop requires an inventory.yml, connecting to FTL2's inventory management system.
• systemd service management — deployment uses systemd units, a pattern common across FTL2 deployment scripts.
• Google OAuth — requires GCP Console configuration for redirect URIs, an external dependency outside the automation scope.
• textual-serve — bridges Textual TUI applications to web access, used here to expose ftl2-htop.
• Pre-baked images — the deployment assumes infrastructure prep is already done via image baking, reducing provisioning steps.

Exam-Relevant Points

• Cloudflare DNS must be set to DNS-only (not proxied) when Caddy handles TLS — proxied mode would intercept the ACME challenge.
• Port 80 must be open even though the app serves HTTPS, because Let's Encrypt's HTTP-01 challenge requires it.
• ftl2-stargate listens on port 8000 (HTTP); Caddy on 443 (HTTPS); textual-serve-htop on 8002.
• Secrets are a manual step — the deployment automation does not handle Google OAuth credentials.
• The textual serve command wraps a TUI app for web access using the -c flag for the command and --port for the listening port.
• Installation uses git+https pip URLs to install directly from GitHub repositories.
• The deployment follows an incremental verification pattern: each layer (DNS, TLS, services) is confirmed before proceeding.