Skip to main content

Nginx / Ingress Strategy

In an enterprise deployment, Nginx is typically used as a reverse proxy to serve static assets and route API traffic to the Framework M modular monolith.

1. Serving Static Assets (ADR-0010)​

Framework M frontend plugins (like the Desk) are packaged within PyPI wheels. For optimal performance, Nginx should serve these files directly rather than proxying them through the Python backend.

Extraction Strategy​

During the Docker build or in an initContainer, static assets should be extracted to a shared volume.

# Example: Extracting Desk assets from the installed package
python -m framework_m_standard.cli assets extract --target /var/www/static

Nginx Configuration​

Once extracted, Nginx can serve the assets from the volume.

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

    root /var/www/static;
    index index.html;

    # Serve static assets directly
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }

    # Proxy API and Dynamic requests to the Backend Monolith
    location /api/ {
        proxy_pass http://framework-m-backend:8888;
        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;
    }

    # SPA Routing: Fallback to index.html for the Desk frontend
    location / {
        try_files $uri $uri/ /index.html;
    }
}

2. Ingress Controllers (Kubernetes)​

When using Kubernetes, the Ingress resource handles routing. The standard ingress-nginx controller is recommended.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: framework-m-ingress
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: desk.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: framework-m-backend
            port:
              number: 8888

3. Performance & Security Tips​

  1. Gzip Compression: Enable gzip for JSON and JavaScript assets.
  2. Buffers: Tune proxy_buffers for large API responses.
  3. SSL/TLS: Always terminate SSL at the Nginx/Ingress level. Use X-Forwarded-Proto so the application knows it is behind a secure proxy.
  4. Static Persistence: In a modular monolith, assets rarely change between deployments. Use aggressive caching for files in the /assets/ directory.

For globally distributed or high-traffic applications, we recommend serving static assets from a CDN (e.g., Cloudflare, CloudFront, Akamai) instead of Nginx.

How it works:​

  1. Push Assets: During CI/CD, extract assets from your built wheels and push them to an S3/GCS bucket that backs the CDN.
  2. Origin Routing:
    • Route /assets/* directly to the CDN/Bucket origin.
    • Route everything else (/api/*, etc.) to your Nginx/Ingress, which then proxies to the Python backend.

Benefits:​

  • Offload: Reduces the load on your Nginx and application pods.
  • Latency: Assets are served from the edge, closer to the user.
  • Cost: S3 + CDN is often cheaper than scaling Nginx instances for high-bandwidth asset delivery.