Document Thruster HTTP/2 Proxy Configuration for Rails Apps

[justin808]

Summary

This issue documents important findings about deploying Rails applications with Thruster HTTP/2 proxy on Control Plane. The current documentation should be updated to help developers avoid common pitfalls.

Background

Thruster is a zero-config HTTP/2 proxy from Basecamp designed for Ruby web applications. It provides HTTP/2 support, asset caching, compression, and early hints. However, its configuration on Control Plane requires specific settings that differ from standalone deployments.

Key Finding: Protocol Configuration

Common Mistake

Developers may assume that to enable HTTP/2, they should set protocol: http2 in the workload port configuration:

# .controlplane/templates/rails.yml - INCORRECT
ports:
  - number: 3000
    protocol: http2  # ❌ Causes 502 errors

Correct Configuration

The workload port should remain as HTTP/1.1:

# .controlplane/templates/rails.yml - CORRECT
ports:
  - number: 3000
    protocol: http  # ✅ Works correctly

Why This Matters

Architecture Comparison

Standalone Thruster (e.g., VPS):

User → HTTPS/HTTP2 → Thruster → HTTP/1.1 → Rails
      (Thruster handles TLS + HTTP/2)

Control Plane + Thruster:

User → HTTPS/HTTP2 → Control Plane LB → HTTP/1.1 → Thruster → HTTP/1.1 → Rails
                      (LB handles TLS)    (protocol: http)  (HTTP/2 features)

What Happens with protocol: http2

Setting protocol: http2 tells Control Plane's load balancer to expect HTTP/2 responses from the container. However:

1. Thruster provides HTTP/2 on the frontend (TLS-terminated connection)
2. Thruster communicates with upstream services via HTTP/1.1
3. The load balancer's HTTP/2 expectation causes protocol negotiation failures
4. Result: 502 Bad Gateway with "protocol error"

What Thruster Provides on Control Plane

Even with protocol: http in the workload configuration, users still get:

• ✅ HTTP/2 protocol to end users (via Control Plane's load balancer)
• ✅ Asset caching and compression
• ✅ Efficient static file serving
• ✅ Early hints support
• ✅ HTTP/2 multiplexing features

Required Dockerfile Configuration

For Thruster to work on Control Plane, the Dockerfile CMD must use Thruster:

# .controlplane/Dockerfile
CMD ["bundle", "exec", "thrust", "bin/rails", "server"]

Important: On Control Plane/Kubernetes, the Dockerfile CMD determines container startup, NOT the Procfile. This differs from Heroku where the Procfile is used.

Recommended Documentation Updates

1. Add Thruster Configuration Guide

Suggest adding a section to the documentation covering:

• How to configure Thruster in Dockerfiles
• Why protocol: http is required (not http2)
• Architecture diagrams showing protocol flow
• Benefits Thruster provides on Control Plane

2. Update Workload Template Examples

If there are example workload templates, ensure they document:

ports:
  - number: 3000
    protocol: http  # Required for Thruster - do not use http2

3. Add Troubleshooting Section

Common issues and solutions:

• 502 errors with "protocol error": Check protocol: http is set
• Verifying Thruster is running: cpln workload exec ... -- cat /proc/1/cmdline
• Testing internal connectivity: cpln workload exec ... -- curl localhost:3000

Example Implementation

We've successfully implemented this in the react-webpack-rails-tutorial repository:

• PR: Enable Shakapacker early hints react-webpack-rails-tutorial#687
• Documentation: .controlplane/readme.md
• Working example: Deployed and verified on Control Plane QA app

Debugging Commands

For troubleshooting Thruster deployments:

# Verify Thruster is running
cpln workload exec <workload> --gvc <gvc> --org <org> --location <location> -- cat /proc/1/cmdline

# Test internal Rails connectivity
cpln workload exec <workload> --gvc <gvc> --org <org> --location <location> -- curl -s localhost:3000

# Check workload configuration
cpln workload get <workload> --gvc <gvc> --org <org> -o json | grep -A 3 "ports"

Benefits for Users

Adding this documentation will:

1. Prevent common 502 protocol errors
2. Help developers understand Control Plane's architecture
3. Enable HTTP/2 benefits with minimal configuration
4. Provide clear troubleshooting guidance

References

• Thruster GitHub: https://github.com/basecamp/thruster
• Rails 8 with Thruster by DHH: https://world.hey.com/dhh/rails-8-with-thruster-by-default-c953f5e3
• Working implementation: Enable Shakapacker early hints react-webpack-rails-tutorial#687

Thank you for considering this documentation enhancement!