Reverse Proxy Integration

MicroFly delegates public TLS termination, HTTP/2/3 handling, and ACME (Let's Encrypt) certificate management to an external reverse proxy. MicroFly's internal ingress engine binds exclusively to loopback (127.0.0.1:8000), routing requests by Host header to the active release.

Internet (Ports 80 / 443, Public TLS)
                 │
                 ▼
    Reverse Proxy (Caddy / Nginx / Apache2)
                 │  (Preserves Host & X-Forwarded-* headers)
                 ▼
    MicroFly Ingress (127.0.0.1:8000)
                 │  (Resolves domain -> active release)
                 ▼
    Workload Service (127.0.0.1:3000+)

MicroFly provides built-in CLI helpers to generate boilerplate configuration for popular web servers:

microfly init-proxy caddy
microfly init-proxy nginx
microfly init-proxy apache2

---

1. Caddy (Recommended)

Caddy is the recommended reverse proxy for MicroFly because it handles automatic HTTPS, certificate generation, renewal, and HTTP/2/3 without manual configuration.

Generating Configuration

Run:

microfly init-proxy caddy

Setup Instructions

1. Install Caddy on Debian/Ubuntu:

   sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl
   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
   sudo apt-get update
   sudo apt-get install -y caddy

2. Edit /etc/caddy/Caddyfile:

   # Global reverse proxy for all domains managed by MicroFly
   {
       # Enable automatic HTTPS
       email [email protected]
   }
   
   # Wildcard or specific domains routed to MicroFly
   *.example.com, example.com, *.localhost {
       reverse_proxy 127.0.0.1:8000
   }

3. Reload Caddy:

   sudo systemctl reload caddy

---

2. Nginx

If your infrastructure standardizes on Nginx:

Generating Configuration

Run:

microfly init-proxy nginx

Setup Instructions

1. Create /etc/nginx/sites-available/microfly:

   server {
       listen 80;
       listen [::]:80;
       server_name example.com *.example.com;
   
       # Optional: Redirect HTTP to HTTPS
       # return 301 https://$host$request_uri;
   
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_http_version 1.1;
   
           # Essential forwarding headers
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_set_header X-Request-ID $request_id;
   
           # WebSocket and streaming support
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
   
           # Timeouts
           proxy_connect_timeout 5s;
           proxy_read_timeout 60s;
           proxy_send_timeout 60s;
       }
   }

2. Enable the site and reload Nginx:

   sudo ln -s /etc/nginx/sites-available/microfly /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx

3. For HTTPS, use Certbot:

   sudo apt-get install -y certbot python3-certbot-nginx
   sudo certbot --nginx -d example.com -d "*.example.com"

---

3. Apache HTTP Server (apache2)

Generating Configuration

Run:

microfly init-proxy apache2

Setup Instructions

1. Enable required Apache modules:

   sudo a2enmod proxy proxy_http proxy_wstunnel headers ssl rewrite

2. Create /etc/apache2/sites-available/microfly.conf:

   <VirtualHost *:80>
       ServerName example.com
       ServerAlias *.example.com
   
       ProxyPreserveHost On
       RequestHeader set X-Forwarded-Proto "http"
   
       ProxyPass / http://127.0.0.1:8000/
       ProxyPassReverse / http://127.0.0.1:8000/
   </VirtualHost>

3. Enable the virtual host and reload Apache:

   sudo a2ensite microfly.conf
   sudo apache2ctl configtest
   sudo systemctl reload apache2

---

Forwarding Headers & Security Rules

MicroFly relies on the reverse proxy to sanitize external headers. For security:

• Host: MicroFly routes traffic exclusively based on the Host header. It must match a domain listed in the application's app.toml domain list.
• X-Forwarded-For: MicroFly walks trusted proxy chains from right-to-left to determine client IPs for rate-limiting and audit logging.
• X-Forwarded-Proto: Informs applications whether the client connected via http or https.
• X-Request-ID: Passed along to backend application processes and recorded in MicroFly access logs. If absent, MicroFly generates a unique UUIDv4.