easy-proxy

A CLI for running an nginx reverse proxy with automatic Let's Encrypt SSL — no hand-edited nginx config, no manual certificate juggling.

easy-proxy (npm: @ethiclab/easy-cli) runs an nginx + certbot container and lets you add reverse-proxy vhosts and obtain wildcard HTTPS certificates from a single command.

What it does

Say you have services running on local ports — a dashboard on :8080, an API on :8081 — and you want to reach them at real hostnames over HTTPS (app.example.com, api.example.com) instead of localhost:8080.

easy-proxy:

1. runs an nginx reverse proxy in Docker (ports 80/443);
2. generates nginx vhosts from templates — easy proxy new http|https ...;
3. obtains Let's Encrypt SSL certificates via the DNS-01 challenge, automated for supported DNS providers (IONOS, Route53, Cloudflare, DigitalOcean, RFC2136).

No nginx configuration files to edit by hand.

Requirements

• Docker 20.10+
• Node.js — the CLI ships as an npm package

Installation

npm install -g @ethiclab/easy-cli

Set these environment variables (add them to ~/.zshrc or ~/.bashrc so they persist):

export EASY_LETSENCRYPT_DIR="$HOME/.easy-proxy/letsencrypt"   # certificates (persistent)
export EASY_DOMAINS_DIR="$HOME/.easy-proxy/domains"           # generated vhosts
export EASY_LETSENCRYPT_EMAIL="[email protected]"               # Let's Encrypt account email
mkdir -p "$EASY_LETSENCRYPT_DIR" "$EASY_DOMAINS_DIR"

Then build the image and start the proxy:

easy proxy build      # build the ethiclab/nginx-easy image
easy proxy create     # start the proxy on :80 and :443
easy proxy status     # prints the container id when running

Note. easy proxy build builds the ethiclab/nginx-easy image locally from a single self-contained Dockerfile (FROM certbot/certbot:latest) — no custom base image and no registry needed.

Quick start — HTTP

easy proxy create
easy proxy new http app.example.com example.com http://host.docker.internal:8080
easy proxy reload

http://app.example.com is now proxied to your service on port 8080. app.example.com must resolve to the host running the proxy — via DNS, or via /etc/hosts for local testing.

Quick start — HTTPS with Let's Encrypt

Obtain a wildcard certificate for your domain via the DNS-01 challenge, then add an HTTPS vhost. Example with IONOS:

# IONOS API credentials — via environment variables...
export IONOS_API_KEY="..."
export IONOS_API_SECRET="..."
# ...or via the `pass` password manager:
#   pass insert ionos/api-key
#   pass insert ionos/api-secret

easy proxy certbot-ionos example.com     # wildcard cert: example.com + *.example.com
easy proxy new https app.example.com example.com http://host.docker.internal:8080
easy proxy reload

For manual DNS-01 with any provider use easy proxy certbot; for RFC2136/BIND use easy proxy rfc2136.

Commands

Run easy proxy help for the full list.

| Command | Description | |---|---| | easy proxy create | Start the proxy container on ports 80/443 | | easy proxy build | Build the ethiclab/nginx-easy image | | easy proxy new http\|https <fqdn> <domain> <target> | Add a reverse-proxy vhost | | easy proxy certbot-ionos <domain> | Wildcard SSL cert via IONOS DNS-01 (automated) | | easy proxy certbot | SSL cert via manual DNS-01 (interactive) | | easy proxy rfc2136 | SSL cert via RFC2136/BIND DNS | | easy proxy reload | Reload nginx after adding or changing vhosts | | easy proxy status | Container id if running, empty if stopped | | easy proxy id | Container id (running or stopped) | | easy proxy doctor | Read-only diagnostic: non-standard vhosts, nginx -t, proxy networks | | easy proxy verify | Check the proxy is actually running; create runs it automatically | | easy proxy recover [--consolidate] | Break-glass: find the backends' networks, connect the proxy, restart | | easy proxy attach / detach <container> | Connect/disconnect a site container to the edge network | | easy proxy networks [prune] | Show the proxy's networks; prune disconnects non-edge ones | | easy proxy start / stop / restart | Container lifecycle | | easy proxy sh | Interactive shell in the container | | easy proxy log | Follow the container logs | | easy proxy destroy | Stop and remove the container |

Upgrading to 2.0

2.0.0 is a major release with breaking changes from 1.x:

• Container identity. The proxy container is identified by the fixed name easy-proxy instead of a .id state file. A container created by 1.x is not visible to 2.0 — remove it with docker rm -f <container> and run easy proxy create again.
• Docker image. Rebuilt from scratch on certbot/certbot:latest, with nginx and the DNS provider plugins. Run easy proxy build to rebuild.
• Template engine. Rewritten from Python 2 to Node.js (internal).

See CHANGELOG.md for the full history.

Development

git clone [email protected]:ethiclab/easy-proxy.git
cd easy-proxy
. ./configure-local-devenv     # put the repo on PATH

npm test                       # bats test suite
npm run lint                    # ShellCheck

The full developer guide — architecture, the IONOS automation flow, gotchas — is in CLAUDE.md.

Credits

Originally inspired by jwilder/nginx-proxy.

License

MIT