Minipx

A simple, fast, and configurable TCP/IP reverse proxy written in Rust with automatic SSL certificate management via Let's Encrypt.

• 🚀 High Performance: Built with Rust and Tokio for excellent performance and memory safety
• 🔒 Automatic SSL (HTTPS): Integrated Let's Encrypt support with automatic certificate provisioning and renewal via ACME (TLS-ALPN-01)
• 🌐 Multi-Domain: Serve multiple domains with individual certificates (no wildcard certs)
• 🔁 Smart Redirects: Optional per-route HTTP→HTTPS redirects that only occur when TLS is actually available for that host
• 🧩 Config Hot-Reload: JSON-based configuration with live updates and graceful restarts of the HTTPS server when needed
• 🧰 SSL Toggle: Global config flag to enable/disable the HTTPS server without changing routes
• 📊 Logging: Configurable logging levels for monitoring and debugging

Download the latest release from the releases page or build from source:

git clone <repository-url>
cd minipx
cargo build --release

Install using the provided script:

sudo bash -c "$(curl -sSL https://raw.githubusercontent.com/Drew-Chase/minipx/master/install.sh)" < /dev/tty

sudo curl -sSL https://raw.githubusercontent.com/Drew-Chase/minipx/master/install.sh | bash -s -- --uninstall

1. Create a configuration file (see Configuration below), then run:

minipx --config ./minipx.json

2. Run with configuration watching enabled (hot-reload):

minipx --watch --verbose --config ./config/config.json

Note: The configuration directory will be created automatically if it doesn't exist.

• HTTP server listens on the configured port (default 80) on 0.0.0.0.
• HTTPS server listens on port 443 on [::] (all IPv6/IPv4 via dual-stack), automatically handling ACME TLS-ALPN-01 challenges and serving TLS.
• When a route has redirect_to_https = true, HTTP requests are redirected to HTTPS only if a certificate can be served for that host; otherwise, the request is served over HTTP and a warning is logged.

# Basic usage with default config
minipx

# Use custom config with verbose logging
minipx --verbose --config /etc/minipx/config.json

# Enable hot-reload with configuration watching
minipx --watch --verbose --config ./config/config.json

# You can also concat the short options together
minipx -wvc /etc/minipx/config.json

Minipx uses a JSON configuration file to define proxy behavior, SSL settings, and routing rules.

Each entry under routes maps a domain (e.g., "api.example.com") to proxy settings.

Notes:

• Wildcard route keys (like "*.example.com") are supported for routing lookups, but wildcard certificates are NOT requested. Only exact domains are used for ACME.

{
  "email": "admin@mydomain.com",
  "port": 80,
  "cache_dir": "./ssl-cache",
  "ssl_enabled": true,
  "routes": {
    "api.mydomain.com": {
      "host": "localhost",
      "path": "/api/v1",
      "port": 3000,
      "protocol": "http",
      "redirect_to_https": true
    },
    "app.mydomain.com": {
      "host": "192.168.1.100",
      "port": 8080,
      "protocol": "http",
      "redirect_to_https": true
    },
    "secure.mydomain.com": {
      "host": "backend-server",
      "port": 443,
      "protocol": "https",
      "redirect_to_https": false
    }
  }
}

Minipx uses rustls-acme with the Let's Encrypt production directory.

• Validation: TLS-ALPN-01 (served on port 443). No HTTP-01 is used.
• Certificate caching: Stored in cache_dir to avoid rate limits.
• Multi-domain: Certificates are requested for all valid, exact domains present as keys in routes.
• Wildcards: Not supported for certificates. Wildcard route keys are ignored for ACME.

Requirements:

• Domains must resolve to this server.
• Port 443 must be publicly accessible for TLS-ALPN-01 validation and HTTPS traffic.
• A valid email must be provided for the ACME account. If the email is invalid, the HTTPS server won’t start and will wait for a valid config.

Behavior with invalid config:

• If ssl_enabled is false: HTTPS server does not start (waits for enablement via hot-reload).
• If email is invalid: HTTPS server waits until a valid email is provided.
• If some domains are invalid: HTTPS starts for valid domains only and logs the skipped ones.
• HTTP→HTTPS redirects occur only when a certificate can be served for that host; otherwise traffic is served over HTTP and a warning is logged.

Hot-reload behavior:

• Changes to ssl_enabled, email, cache_dir, or the set of valid domains trigger a graceful HTTPS server restart.

Minipx uses structured logging with different levels:

• Error: Critical errors and failures
• Warn: Warning messages and recoverable errors
• Info: General information about proxy operations
• Debug/Trace: More detailed logs (enabled with --verbose)

Set the RUST_LOG environment variable for custom log levels:

RUST_LOG=debug minipx --config config.json

Common issues:

1. Binding to privileged ports (80/443)

• On Linux/macOS, run with sudo or use capabilities (e.g., setcap) to bind <1024.
• Ensure no other service is using the port.

2. Certificate acquisition failures

• Verify DNS records resolve to this server.
• Ensure port 443 is reachable from the internet.
• Check that cache_dir is writable and persistent.
• Confirm email is valid.

3. Backend connection refused

• Verify target service is running and reachable from Minipx.
• Check host, port, and protocol in your route configuration.

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

This project is licensed under the MIT License — see the LICENSE file for details.

Built with these excellent Rust crates:

• tokio — Async runtime
• hyper — HTTP implementation
• rustls — TLS implementation
• rustls-acme — Let's Encrypt integration
• serde — Serialization framework
• clap — Command line argument parsing