Skip to content

Nginx Development Setup Guide

Nginx Development Setup Guide

Overview

The Tracker stack uses nginx in two places:

  • locally, as an optional reverse proxy in front of the Docker Compose dev stack
  • in AWS frontend deployments, where the frontend and API traffic still depend on nginx-style proxy headers and HTTPS handling

This page documents the small set of nginx behaviors that matter in both places. For AWS topology and deployment details, see Terraform Deployment Guide and Infrastructure Reference.

Core Rules

Keep these behaviors consistent:

  • preserve the incoming Host header
  • forward X-Forwarded-For
  • set X-Forwarded-Proto correctly
  • use WebSocket-compatible proxy headers for the frontend
  • keep trailing-slash handling consistent with the API

If nginx terminates or forwards HTTPS, follow HTTPS Behind a Load Balancer. For request-path consistency and redirect handling, follow API URL Handling.

Local Docker Compose Example

Use service names inside Compose rather than localhost:

server {
    listen 80;
    server_name localhost;

    resolver 127.0.0.11 ipv6=off;
    resolver_timeout 5s;

    location /api/ {
        proxy_pass http://dev:8000/api/;
        proxy_http_version 1.1;
        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;
    }

    location /admin/ {
        proxy_pass http://admin-dev:3000/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location / {
        proxy_pass http://frontend-dev:3000/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

AWS Frontend Notes

The AWS frontend still uses nginx-oriented proxy behavior, so the same rules apply:

  • keep X-Forwarded-Proto aligned with the external scheme
  • avoid returning http:// redirects when the browser is already on HTTPS
  • keep API and frontend hostnames consistent with the deployed domain

The exact infrastructure layout lives in:

Troubleshooting

  • If requests downgrade to HTTP, check X-Forwarded-Proto and any redirect rules.
  • If WebSocket connections fail, confirm proxy_http_version 1.1 plus Upgrade and Connection headers.
  • If nginx cannot resolve upstream containers, confirm the Docker DNS resolver and service names.
  • If API redirects look inconsistent, check the trailing-slash rules in API URL Handling.

References