How-To: Production Proxy Configuration

In a Macroservice deployment, the Gateway or Reverse Proxy (Nginx, Traefik, Caddy) is responsible for deterministic routing based on path prefixes. This configuration is driven by the routes.json blueprint.

The Routing Blueprint

The routes.json file defines how external request paths map to internal services.

{
  "/api/finance/": {
    "target": "http://finance-service:8000/api/finance/",
    "service": "finance"
  },
  "/mfe/finance/": {
    "target": "http://finance-mfe-static:80/",
    "service": "finance"
  }
}

1. Nginx Translation

For Nginx, each entry in the JSON translates to a location block.

API Routing

Deterministic routing ensures that /api/{service}/ requests always hit the correct backend.

# Finance Service API
location /api/finance/ {
    proxy_pass http://finance-service:8000/api/finance/;
    proxy_set_header X-Framework-M-Service finance;
    include proxy_params;
}

MFE Asset Routing

Static assets for Micro-Frontends are served via the /mfe/ prefix.

# Finance MFE Assets
location /mfe/finance/ {
    proxy_pass http://finance-mfe-static:80/;
    add_header Access-Control-Allow-Origin *;
}

2. Traefik Translation (Labels)

If using Traefik, these rules are typically defined via Docker labels or File Provider routers.

http:
  routers:
    finance-api:
      rule: "PathPrefix(`/api/finance/`)"
      service: finance-backend
      middlewares:
        - service-header-finance

  middlewares:
    service-header-finance:
      headers:
        customRequestHeaders:
          X-Framework-M-Service: "finance"

  services:
    finance-backend:
      loadBalancer:
        servers:
          - url: "http://finance-service:8000"

3. Header-Based Routing

The X-Framework-M-Service header is critical. While the proxy routes based on the Path, the backend services use this header to validate that the request was intended for them. This prevents "routing leakage" in complex federated environments.

[!IMPORTANT] Your proxy MUST set the X-Framework-M-Service header to match the service key in the JSON blueprint. This is required for the backend's security and telemetry layers.