Self-Host Twrctrl: Browser ATC Simulator on Docker & Caddy

Twrctrl recently made the rounds on Hacker News, showing off an open-source, browser-based air traffic control simulator focused on airport tower and ground operations. If you have spent any time with legacy flight simulation tools—EuroScope, VRC, or commercial desktop packages like Tower!3D—you know the administrative tax. You deal with massive multi-gigabyte asset packs, brittle Windows-only runtimes, manual port forwarding for direct UDP peer connections, and configuration files that look like raw memory dumps from 2004.

Twrctrl takes the opposite route. The server runs as a lightweight daemon that handles aircraft coordinates, runway state, and flight strip updates, while the client runs entirely inside an ordinary browser tab over WebSockets. For homelabbers, this design is an easy win. You can package the backend in a hardened Docker container, put it behind your existing reverse proxy, and launch an approach control session on a low-power laptop, an iPad, or a workstation without installing a single local binary.

Setting this up cleanly requires some care. WebSockets behave differently from standard stateless HTTP traffic, and long stretches of quiet runways will trip up aggressive proxy timeouts. Here is how the underlying architecture works, how to package it cleanly with Docker Compose, and how to tune your proxy so connections stay stable.

Architectural Profile: Browser Rendering vs. Desktop Stacks

Traditional ATC simulators treat the local workstation as both the graphics engine and the simulation authority. If you run a simulation with 40 active aircraft, your desktop CPU calculates flight paths, runs collision-prediction algorithms, and renders 3D models or dense vector scopes simultaneously.

Twrctrl splits the workload cleanly down the middle:

• The Server Backend: Acts as an authoritative state coordinator. It manages the internal simulation clock, advances aircraft waypoints, runs separation checks, handles runway occupancy logic, and broadcasts state deltas over WebSockets.
• The Client Browser: Receives the coordinate packets and draws the radar sweeps, airport ground diagrams, and flight progress strips using WebGL and the HTML5 Canvas API. It also uses the Web Audio API for radio clicks and alert chimes.

This division shifts almost all rendering overhead to the client. The heavy lifting happens on the graphics processor of whatever device opens the URL, leaving your homelab server free to handle pure network I/O and state synchronization.

Because the server state is decoupled from the user interface, you can run the backend continuously on a low-power mini PC or home server without keeping a power-hungry desktop graphics card spinning.

Deploying Twrctrl with Docker Compose

Running interactive web simulations in a homelab works best when you lock down the container. Because the backend only serves static assets and relays real-time event packets, you do not need root access inside the container, external storage volumes, or write permissions to the application directory.

Create a dedicated directory on your server and save the following configuration as docker-compose.yml:

services: twrctrl: image: ghcr.io/your-repo/twrctrl:latest # Replace with your target image container_name: twrctrl restart: unless-stopped user: "1000:1000" read_only: true security_opt: - no-new-privileges:true ports: - "127.0.0.1:8080:8080" environment: - PORT=8080 - NODE_ENV=production - SIM_TICK_RATE=20 # 20 Hz simulation state updates tmpfs: - /tmp:rw,noexec,nosuid,size=32m deploy: resources: limits: cpus: "1.00" memory: 256M reservations: cpus: "0.10" memory: 64M healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"] interval: 30s timeout: 5s retries: 3

A few operational choices in this file deserve attention:

• read_only: true: Locks the entire root filesystem inside the container. If an unknown flaw exists in the web server, an attacker cannot write malicious files to disk or overwrite application binaries.
• user: "1000:1000": Forces the container to run under an unprivileged user ID rather than root.
• tmpfs: /tmp: Gives the application a tiny 32 MB in-memory scratch space for temporary PID files or socket handles. Because it uses the noexec flag, no code can execute from this partition.
• 127.0.0.1:8080:8080: Binds the port strictly to the local host interface. This prevents the port from being exposed across your local network before traffic passes through your reverse proxy.

Start the service and check the initial startup logs:

docker compose up -d
docker compose logs -f twrctrl

You can confirm the health status directly from the Docker engine:

docker inspect --format='{{json .State.Health.Status}}' twrctrl

If it returns "healthy", the service is ready for proxy traffic.

Configuring Caddy for Persistent WebSockets

The primary failure point for browser-based simulators is the reverse proxy. In standard web applications, HTTP requests complete in a few milliseconds. In an air traffic control simulator, a WebSocket connection must stay open for hours at a time.

If an aircraft sits on a taxiway waiting for departure clearance and no state updates cross the wire for 60 seconds, standard reverse proxy timeouts assume the client disappeared and sever the connection. When that happens, your radar sweep freezes, target tags vanish, and you must reload the page to catch up.

Here is how to set up Caddy to maintain persistent simulator connections:

atc.home.arpa {
    encode gzip zstd

    reverse_proxy 127.0.0.1:8080 {
        # WebSocket connections require long timeouts
        transport http {
            read_timeout 3600s
            write_timeout 3600s
            keepalive 60s
        }

        # Pass real client attributes for accurate logging
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up Connection {>Connection}
        header_up Upgrade {>Upgrade}
    }
}

By pushing read_timeout and write_timeout to an hour (3600s), Caddy allows the simulation stream to remain open even during quiet periods on the field.

If you run Traefik instead, define dynamic labels on your container to configure the transport layer:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.twrctrl.rule=Host(`atc.home.arpa`)"
  - "traefik.http.routers.twrctrl.entrypoints=websecure"
  - "traefik.http.services.twrctrl.loadbalancer.server.port=8080"
  - "traefik.http.services.twrctrl.loadbalancer.responseForwarding.flushInterval=100ms"

The flushInterval=100ms parameter forces Traefik to forward small WebSocket frames immediately rather than buffering them into larger network packets. This keeps aircraft position sweeps responsive.

Common Traps and Gotchas

Running simulation software in a browser changes where performance bottlenecks emerge. Keep an eye out for these operational snags:

1. Browser Tab Memory Leaks

Because Canvas and WebGL contexts redraw moving targets 30 to 60 times per second, long sessions can consume significant client memory. On your server, Twrctrl will comfortably sit between 35 MB and 65 MB of RAM. On your laptop, however, a tab left open for four hours can drift from 250 MB past 600 MB if the browser engine delays its garbage collection cycles.

If your radar display begins dropping frames or feels sluggish when panning across the airfield diagram, check the browser task manager (Shift+Esc in Chrome or about:performance in Firefox). Reloading the tab clears the browser heap without losing server-side state.

2. Clock Drift Between Server and Client

Simulators rely on coordinated universal time (UTC) to calculate ground speeds, arrival sequencing, and separation minimums. If your homelab server clock drifts by even three seconds while your workstation stays locked to an external NTP server, aircraft icons will stutter across the screen as the client tries to interpolate past positions with future server updates.

Ensure your host system clock is synchronized using systemd-timesyncd or chrony:

timedatectl status

Verify that the output shows NTP service: active and System clock synchronized: yes. If you run chrony, you can verify your time source offset directly:

chronyc tracking

3. Missing WebSocket Upgrades on Subpaths

If you host your simulator behind a URL path instead of a dedicated root subdomain (for example, home.arpa/twrctrl instead of atc.home.arpa), some reverse proxies fail to pass the Upgrade: websocket and Connection: Upgrade headers down to subfolders.

Unless you enjoy writing custom rewrite and header-stripping rules, assign real-time web applications their own subdomain or local split-horizon DNS entry.

4. Background Tab Throttling

Modern web browsers heavily throttle inactive tabs to preserve battery life. If you move Twrctrl to a secondary monitor and click into a different window, Chrome, Firefox, and Safari will downscale timers (setTimeout and requestAnimationFrame) to as low as 1 Hz.

When this happens, the WebSocket connection stays open, but the browser stops drawing intermediate position sweeps. When you click back into the window, the client tries to process dozens of queued position frames all at once, causing aircraft to dart erratically across the runway. To avoid this, keep the window focused or disable background tab throttling for your internal domain via browser flags (chrome://flags/#calculate-native-win-occlusion on Chromium).

Frequently Asked Questions

Can you self-host browser-based ATC simulators like Twrctrl with Docker?

Yes. The server component runs as a standard Node.js, Go, or Rust binary that serves static HTML/JS assets and coordinates real-time state using WebSockets. Packaging it inside a lightweight Alpine-based Docker container takes minimal effort. It requires no specialized GPU passthrough, kernel modules, or privileged access on the host system.

How do you configure Caddy or Traefik reverse proxies for WebSocket-based web simulators?

You must explicitly configure your proxy to handle long-lived connections. Generic HTTP proxies assume connections that fall idle for 30 to 90 seconds are broken and close them. In Caddy, set your read_timeout and write_timeout values to 3600s or higher inside the transport http block. In Traefik, ensure your router does not enforce aggressive response timeouts, and set flushInterval to a low value (such as 100ms) so packet deltas are delivered instantly.

What are the CPU and RAM baselines for hosting web-based simulation tools in a homelab?

The server requirements are exceptionally modest:

• CPU: 1 vCPU (averaging below 5% utilization on modern x86 or ARM chips).
• Host RAM: 35–65 MB at idle, rarely exceeding 180 MB under continuous multi-target simulation.
• Client RAM: 250–550 MB inside the user's browser tab to hold the WebGL canvas contexts, audio buffers, and interface elements.

How do browser-based radar simulations compare to desktop ATC clients like Tower!3D?

Desktop simulators offer commercial airport terrain models, speech recognition, and complex 3D aircraft models, but they demand dedicated gaming hardware and run almost exclusively on Windows. Browser-based simulators trade visual fidelity for immediate access. They focus on clean 2D top-down ground control, radar screens, and flight strips. This allows them to run on low-power home servers, tablets, or older laptops without installing proprietary client software.

Verdict

Browser-based simulators like Twrctrl show how modern web standards can replace bloated local software. By offloading rendering to the client's browser engine, you can host a responsive ground control simulator on modest server hardware. Lock your container down with an unprivileged user and a read-only filesystem, configure your reverse proxy to respect long WebSocket timeouts, and you will have a stable, responsive radar tower running directly inside your home network.

Related in this cluster

• /en/posts/cursor-xai-vs-local-llms-privacy-guide-for-homelabs/
• /en/posts/docker-sandbox-kit-spec-v3-hardening-ai-agent-containers/
• /en/posts/docker-sandboxes-secure-isolation-for-autonomous-ai-agents/