Pingap Review: Pingora Reverse Proxy with a Built-in Admin

Pingap's Reverse Proxy and Gateway Scope

Pingap addresses operators who need more request forwarding than a basic reverse proxy provides. Its purpose is to route incoming HTTP traffic to upstream services while adding policies around authentication, access control, traffic, content, and operations. The upstream service can be another network host, a DNS-discovered endpoint group, or a service represented through configuration. This places Pingap between public traffic and application servers rather than acting as an application framework itself.

The project is written in Rust and is built on Cloudflare Pingora. The repository identifies Pingap as a reverse proxy like nginx, but its scope is broader than a configuration-only proxy. It supports HTTP/1.1, HTTP/2, WebSocket, and gRPC-web, according to the README. Routing can use hosts, paths, and regular expressions, while upstream selection includes round robin, least connections, consistent hashing, and sticky sessions. These choices matter when one public endpoint fronts several instances of an application.

Pingap also treats configuration as part of operational control. The README describes a web admin embedded in the binary, TOML configuration files, HCL and KDL alternatives, and etcd-backed configuration. This design targets operators who need to change routes and policies without maintaining a separate administration service. It also creates a larger security and configuration surface, so the embedded admin should be considered part of the production deployment rather than a convenience layer.

Configuration, Reloads, and Validation

Pingap uses a layered configuration model. A server owns listener settings and references locations. A location selects an upstream and can attach plugins. Upstreams contain addresses and discovery settings. The following repository example demonstrates that structure by defining a DNS-discovered GitHub API upstream, a static file plugin, two locations, and a server listening on `127.0.0.1:6118`.

[upstreams.api]
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"

[plugins.staticServe]
category = "directory"
path = "~/Downloads"

[locations.github-api]
upstream = "api"
path = "/api"
proxy_set_headers = ["Host:api.github.com"]
rewrite = "^/api/(?<path>.+)$ /$1"

[locations.static]
plugins = ["staticServe"]

[servers.test]
addr = "127.0.0.1:6118"
locations = ["github-api", "static"]

The documented reload modes differ by operation. `--autoreload` applies changes within ten seconds when they come from files, and immediately when they come from etcd. It reports changes that need a restart and waits for that restart. `--autorestart` additionally handles listener changes with a restart that hands sockets over for a daemon on Linux. The README says that the running process continues serving if its replacement fails to start. Outside Linux daemon mode, the documented behavior is to reload and report what waits.

Validation is explicit. `-t` builds every upstream, location, plugin, certificate, and server as a start would, but it binds nothing. `--strict` turns unknown keys and unavailable feature-specific keys into errors, making it appropriate for configuration checks. `--diff <other>` prints the changes that would result from replacing the current configuration, with credentials represented as checksums. These commands make configuration review more concrete than editing a file and waiting for a deployment failure.

Installing Pingap and Starting the First Proxy

The README offers Docker Compose, a release installation script, and a single-command mode. Docker Compose is the clearest path for a persistent gateway because the service stores configuration, certificates, and cache under `/opt/pingap`. Replace the example password before starting it.

mkdir pingap_data
docker compose up -d

The Compose example maps ports `80:80` and `443:443`, sets `PINGAP_CONF=/opt/pingap/conf`, and starts Pingap with `--autoreload`. The admin is documented at `http://localhost/pingap`. The repository's own `docker-compose.yml` uses a different admin address, `0.0.0.0:3018`, and includes a separate host mapping for port `3018`. That difference means operators should follow the deployment file they actually use rather than assume both examples configure the same endpoint.

For Linux and macOS, the README gives this installation command. It installs the latest release to `/usr/local/bin/pingap`.

curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | sh

A first proxy can then be started from the command line without a configuration file.

pingap --domain=pingap.io --upstream=192.168.1.1:3000

Without `--cert`, Pingap obtains a Let's Encrypt certificate through HTTP-01. The domain must resolve to the host and port 80 must be reachable. The certificate is stored under `~/.pingap/acme/<domains>.toml` and reused at the next start. To provide an existing certificate instead, the documented form is:

pingap --domain=pingap.io --upstream=192.168.1.1:3000 --cert=/etc/ssl/pingap.io

The `--domain` and `--upstream` options accept comma-separated lists. This one-command mode recreates its configuration at every start, so the admin cannot edit it. Persistent, multi-server deployments need a configuration file or an etcd setup.

Plugin Chains and Application Gateway Policies

Pingap's distinguishing feature is its plugin chain attached to each location. The README lists more than thirty plugins across authentication, access rules, traffic, content, and operations. Plugins execute in the order specified for the location, so ordering is part of the behavior rather than an incidental list.

Authentication plugins include JWT, OIDC, key, basic, HMAC, and forward authentication. Access plugins can restrict requests by IP address, referer, user agent, or blocked path. Traffic plugins provide rate limits, bandwidth limits, caching, mirroring, and traffic splitting. Content plugins include compression, body substitution, redirects, static files, and image optimization. Operational plugins can enable maintenance mode, health endpoints, and custom error pages.

This model is useful when the proxy is the enforcement point for several services. For example, a location can require authentication, reject a path, limit requests, and then forward the remaining traffic. However, a long ordered chain makes the effective request path harder to inspect than a short list of routing rules. The admin checks a change before storing it, but operators still need to understand which plugin runs first and what happens when a plugin rejects a request.

The README also states that metrics, tracing, and image optimization are included in the `-full` builds. This distinction matters when comparing image tags. The release image variants include `latest`, `full`, and `rustls-full`, with versioned equivalents. A deployment that needs observability or image processing should confirm which binary variant is being used rather than assuming every image contains every optional feature.

Certificates, TLS, and Runtime Backends

Certificate management is built into the gateway rather than delegated entirely to an external renewal job. The README documents Let's Encrypt and other ACME certificate authorities, using either HTTP-01 or DNS-01. DNS providers listed include Alibaba Cloud, Cloudflare, Tencent Cloud, and Huawei Cloud. RSA and ECDSA certificates can be used, and the project also documents OCSP stapling plus mutual TLS toward clients and upstreams.

For existing certificates, Pingap recognizes common filename pairs when `--cert` points to a directory. The README lists `fullchain.pem` with `privkey.pem`, `cert.pem` with `key.pem`, and `tls.crt` with `tls.key`. For another naming scheme, `--key` identifies the private key. This is useful in existing infrastructure where certificate files already have an established layout.

TLS implementation choice is another operational decision. The project documents OpenSSL or rustls, and its install variables expose `PINGAP_TLS=rustls` for a Linux `rustls-full` build without OpenSSL. The `-full` build contains the optional features described by the README. Pingap also supports the PROXY protocol on listeners and toward upstreams, which can matter when preserving client address information across another network hop.

The main limitation is that the simple certificate path depends on DNS and network reachability. HTTP-01 requires the domain to resolve to the Pingap host and port 80 to be reachable. DNS-01 adds provider credentials and a second control dependency. Neither approach removes the need to protect the private key, account credentials, and the data directory.

Observability, Upstream Health, and Operational Limits

Pingap includes the operational features expected from a gateway that fronts production services. Prometheus metrics can be pulled or pushed, and OpenTelemetry traces are supported. Access logs can be text or JSON with more than thirty fields. The README also names JA4 TLS fingerprints for client-side TLS metadata. These features are more relevant when request identity, latency, upstream selection, or certificate behavior needs investigation across several services.

Upstreams can use DNS A, AAAA, or SRV discovery, and Docker labels are also documented as a backend source. Health checks, retries, and a circuit breaker are available around upstream traffic. These mechanisms address a specific failure mode: an upstream instance that remains in the address list but cannot serve requests. They do not replace application-level readiness checks, so operators must decide whether a Pingap health check reflects only network availability or the actual service behavior they need.

The embedded admin has read-only accounts and API tokens, according to the README. It also stores earlier versions for restoration. Configuration history is useful for controlled rollback, but the README excerpt does not describe the exact retention policy, backup format, or behavior when the storage volume is lost. In the Docker example, configuration, certificates, and cache are kept under `/opt/pingap`, so treating that directory as persistent state is part of the deployment design.

Pingap is not the right choice when the only requirement is a static, low-control reverse proxy. The plugin model, admin, certificate handling, and multiple configuration formats add decisions that nginx users may not need. It is better suited to teams that need those controls at the gateway and can maintain a Rust binary and its associated state.

Pingap Maintenance and Upgrade Boundaries

The repository is not archived, and the last push was on 2026-10-14. Recent releases include `v0.16.0` on 2026-10-12, `v0.15.0` on 2026-10-01, and `v0.14.3` on 2026-09-13. The release cadence and recent repository activity indicate an actively changing project, although the README does not provide a compatibility policy for configuration files or plugin behavior between releases.

Upgrade planning should therefore focus on concrete project files and commands. The repository includes an upgrading guide and `CHANGELOG.md`. The `-t` command can validate a configuration before startup, and `--diff <other>` can show the effect of replacing the active configuration. The README does not state whether all releases preserve every previous configuration key, so an operator should not assume compatibility solely from the versioned image tag.

The Apache-2.0 license is identified in the repository metadata and `LICENSE` file. That designation governs the project's licensing terms, while operational questions such as suitability for a particular deployment or interaction with other licensed components require separate review. This article does not provide legal advice.

Pingap should be adopted by operators who want an embedded admin and plugin-based policies around Pingora-based proxying. It should not be adopted merely because the homepage describes it as simple and efficient, since the actual cost includes configuration design, certificate credentials, persistent storage, and release verification. The first checks should be the required plugin list, the selected image variant, certificate issuance method, and the behavior of `--autoreload` for the specific deployment.

Editorial conclusion

Adopt Pingap when a small operator needs a configurable gateway with an embedded admin and automated certificate handling. Do not choose it for a static routing-only deployment unless its plugin and reload model justify the additional configuration surface. Before adoption, verify the required plugin features, certificate authority access, persistent storage, and whether changes can be applied with --autoreload or require --autorestart.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. vicanso/pingap on GitHub