← Bosun

Reverse-proxying an app with nginx

The reverse-proxy config most Puma deployments pair with bosun — documentation only, bosun doesn't manage nginx itself.

bosun does not install, configure, or manage nginx — this is a documentation-only reference for the reverse-proxy config most Puma deployments pair with it, pointing at the Unix socket bosun add/ config/puma.rb already create. TLS/certificate management is left entirely to your own tooling (certbot, an internal CA, a load balancer in front of this box, etc.) — not covered here.

Standalone mode (no argus-tty): the socket is owned by your own account and bosun-apps, not literally webapp-svc/webapps — see standalone.md. Nothing about the nginx config below changes either way.

The socket bosun already gives you

Puma binds a Unix socket at:

/var/www/<app>/shared/tmp/sockets/puma.sock

(created by deployment/setup, see mkdir -p "$SHARED_PATH/tmp/sockets"). webapp-svc owns it, group webapps — the same account/group that already own everything else under the app tree.

A per-app server block

One server {} block per app, named after the app so it's easy to keep track of as you add more:

# /etc/nginx/sites-available/myapp
  upstream myapp_puma {
    server unix:/var/www/myapp/shared/tmp/sockets/puma.sock fail_timeout=0;
  }

  server {
    listen 80;
    server_name myapp.example.com;

    # Serve precompiled assets directly, bypass Puma entirely for them.
    location ~ ^/(assets|packs)/ {
      root /var/www/myapp/current/public;
      expires max;
      add_header Cache-Control "public";
    }

    location / {
      proxy_pass http://myapp_puma;
      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;
    }

    client_max_body_size 20m;
  }

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

Notes

• The socket path only exists once the app has had at least one bosun deploy (actually, the socket itself is created by Puma when it starts under puma-<app>.service — the parent directory is created by bosun setup). Starting nginx before the service has ever run is fine — nginx returns 502 until the socket exists, same as any proxied upstream that isn't up yet.
• If you add puma-app_name.socket.sample (socket activation — see docs/systemd.md), the socket path and ownership stay the same; only who creates the file changes (systemd instead of Puma).
• TLS, rate limiting, and any WAF/CDN layer are entirely outside bosun's scope — this file only documents the minimum reverse-proxy wiring to the socket bosun already manages.