ERPNext Pingora Proxy

Production-ready candidate Pingora reverse proxy profile for ERPNext/Frappe benches.

This project routes ERPNext traffic like this:

client -> Pingora
  /socket.io -> ERPNext realtime/socket.io upstream
  everything else -> ERPNext web upstream

It is intended as a second reverse-proxy option beside the common nginx setup. It is not an official ERPNext, Frappe, Pingora, or Cloudflare project.

Production Readiness

This proxy is considered production-ready for an environment only after its production gate passes in that same environment:

./scripts/production-gate.sh

The gate verifies build health, ERPNext web routing, socket.io routing, response headers, and HTTP load behavior.

Validated environment and results:

• docs/tested-matrix.md
• docs/production-validation-report.md

Features

• Pingora-based HTTP reverse proxy
• ERPNext site host forwarding
• /socket.io routing to the realtime service
• X-Forwarded-*, X-Real-IP, and X-Frappe-Site-Name upstream headers
• Health endpoint at /_pingora_health
• Configurable via environment variables

Requirements

• Rust toolchain
• Running ERPNext/Frappe bench
• ERPNext web server, usually on 127.0.0.1:8000
• ERPNext realtime/socket.io server, usually on 127.0.0.1:9000

Configuration

Copy the example env file:

cp .env.example .env

Default values:

PINGORA_LISTEN=127.0.0.1:8088
PINGORA_WEB_UPSTREAM=127.0.0.1:8000
PINGORA_SOCKETIO_UPSTREAM=127.0.0.1:9000
PINGORA_SITE_HOST=erpnext.localhost
PINGORA_FORWARDED_PROTO=http
RUST_LOG=info

Run

Development:

RUST_LOG=info cargo run

Release build:

cargo build --release

With the helper script:

scripts/start-prod.sh
scripts/stop-prod.sh

Then open:

http://127.0.0.1:8088

Health check:

curl http://127.0.0.1:8088/_pingora_health

Production Gate

Run the repeatable production gate:

./scripts/production-gate.sh

See docs/production-gate.md for load-test knobs and release criteria.

Notes

For public production use, verify TLS, domain configuration, service supervision, log rotation, firewall rules, and ERPNext production process management in the target environment.

Pingora is an open-source project by Cloudflare. See the Pingora project and its license before adopting this in production.