NexaPG/docs/deployment/proxy-production-profile.md

Production Proxy Profile (HTTPS)

This profile defines a secure and repeatable NexaPG deployment behind a reverse proxy.

Included Profile Files

• ops/profiles/prod/.env.production.example
• ops/profiles/prod/nginx/nexapg.conf

CORS Recommendations by Environment

Environment	Recommended CORS_ORIGINS	Notes
dev	* or local explicit origins	* is acceptable only for local/dev usage.
staging	Exact staging UI origins	Example: https://staging-monitor.example.com
prod	Exact production UI origin(s) only	No wildcard; use comma-separated HTTPS origins if needed.

Examples:

# dev only
CORS_ORIGINS=*

# staging
CORS_ORIGINS=https://staging-monitor.example.com

# prod
CORS_ORIGINS=https://monitor.example.com

Reverse Proxy Requirements

For stable auth, CORS, and request context handling, forward these headers to backend:

• Host
• X-Real-IP
• X-Forwarded-For
• X-Forwarded-Proto
• X-Forwarded-Host
• X-Forwarded-Port

Also forward API paths:

• /api/ -> backend service (:8000)

Mixed-Content Prevention

NexaPG frontend is designed to avoid mixed-content in HTTPS mode:

• Build/runtime default API base is relative (/api/v1)
• frontend/src/api.js upgrades http API URL to https when page runs on HTTPS

Recommended production setting:

VITE_API_URL=/api/v1

Validation Checklist

1. Open app over HTTPS and verify:
   • login request is https://.../api/v1/auth/login
   • no browser mixed-content errors in console
2. Verify CORS behavior:
   • allowed origin works
   • unknown origin is blocked
3. Verify backend receives forwarded protocol:
   • proxied responses succeed with no redirect/proto issues

CI Validation

Proxy Profile Validation workflow runs static guardrail checks:

• relative VITE_API_URL default
• required API proxy path in frontend NGINX config
• required forwarded headers
• HTTPS mixed-content guard in frontend API resolver
• production profile forbids wildcard CORS