Envoy Proxy Manager

Envoy Proxy Manager is a Docker web UI for Envoy Proxy. Like Nginx Proxy Manager, it handles custom domains, Let's Encrypt SSL, load balancing, and routing without editing YAML files.

Comment

Inspiration

Managing self-hosted services should not require hand-writing reverse-proxy configuration or learning every detail of a proxy server. Nginx Proxy Manager made this accessible for many users; Envoy Proxy Manager explores the same approachable workflow on top of Envoy.

We wanted a dashboard where users can publish applications, manage certificates, protect services, redirect domains, and forward TCP/UDP traffic without manually editing proxy configuration files.

What it does

Envoy Proxy Manager is a Docker-based web interface for managing Envoy Proxy.

Users can create Proxy Hosts for HTTP and HTTPS applications, route custom domains to internal services, and add per-host custom locations for path-based upstream routing. They can request or upload TLS certificates, configure Force SSL, HTTP/2, HSTS, WebSocket support, and trusted forwarded-protocol handling.

It also supports Redirection Hosts, 404 Hosts for retired domains, and Streams for forwarding TCP or UDP traffic. Access Lists provide reusable client-IP allow/deny rules and credential configuration, while user management includes disabled accounts and two-factor authentication.

The management service stores configuration in SQLite or MySQL/MariaDB and publishes validated Envoy xDS resources dynamically rather than requiring users to edit Envoy YAML by hand. Certificates can be assigned to Proxy, Redirection, and 404 Hosts, with usage shown directly in the certificate list.

How we built it

The backend is written in Go and supports SQLite or MySQL/MariaDB. Envoy is configured through an xDS control plane that generates listeners, routes, clusters, endpoints, and TLS secrets from management data.

The frontend is built with React and Vite. Docker packages the management API, UI, Envoy, and certificate tooling; the documentation is built separately with VitePress. The production image is published as elly7001/envoyproxymanager:latest.

Certificate material is validated before storage and delivered to Envoy through SDS. Proxy, Redirection, and 404 Hosts use SNI-based HTTPS listener chains. Force SSL generates HTTP-to-HTTPS redirects, while HSTS and HTTP/2 are applied only when the relevant TLS configuration is active.

Challenges we ran into

The central challenge was preserving a familiar proxy-manager experience while replacing Nginx with Envoy. Envoy's dynamic model is powerful, but routes, listeners, clusters, and certificate secrets must form a consistent resource graph.

Certificate handling was another challenge. Certificate assignment, HTTPS routing, Force SSL, HSTS, renewal, certificate usage, and runtime refreshes all need to stay consistent across several host types. We added validation and tests around generated xDS snapshots so inconsistent resources fail safely.

We also had to translate familiar proxy-manager concepts into Envoy's resource graph: a custom location becomes its own route and upstream cluster; a redirect or 404 host must work on both HTTP and HTTPS; and changing a host must regenerate a coherent listener, route, cluster, endpoint, and secret snapshot.

Accomplishments that we're proud of

  • Built an Envoy management dashboard with a familiar proxy-manager workflow
  • Added dynamic xDS configuration generation
  • Implemented Proxy Hosts, Redirection Hosts, Streams, Access Lists, and certificates
  • Added 404 Hosts for safely retiring domains without sending traffic upstream
  • Added custom locations for path-based upstream routing
  • Added custom certificate upload and validation
  • Added SNI-based HTTPS listeners, HTTP/2 negotiation, HSTS, and SDS certificate delivery
  • Added client-IP access-list enforcement and reusable access-list configuration
  • Added user management and two-factor authentication
  • Packaged and published the application as a Docker image

What we learned

Envoy is more than a traditional reverse proxy: its xDS APIs make dynamic configuration possible, but require careful validation and lifecycle management. A small database change can affect several Envoy resource types, so tests around snapshots and resource references are essential.

We also learned that compatibility is more than a matching UI. Certificate lifecycle, routing behavior, access control, and migration paths matter for users moving from an existing proxy manager.

What's next

  • Complete a one-to-one importer for existing Nginx Proxy Manager /data directories, including SQLite configuration and certificate files
  • Preserve NPM numeric IDs and host/certificate relationships during migration
  • Add a complete external authorization flow for Access List credential checks
  • Improve renewal reporting and failure recovery
  • Add richer traffic, health, and configuration observability
  • Add backup/restore and expanded audit controls

Built With

Share this project:

Updates