A fast, lightweight, and configurable reverse proxy written in Rust with automatic SSL certificate management via Let's Encrypt.
Minipx is a modern reverse proxy solution designed for simplicity and performance. It provides automatic HTTPS with Let's Encrypt, multi-domain routing, hot configuration reloading, and a powerful CLI for management. Built with Rust and Tokio, it offers excellent performance and memory safety.
- 🚀 High Performance: Built with Rust and Tokio for async I/O
- 🔒 Automatic SSL: Integrated Let's Encrypt with ACME (TLS-ALPN-01)
- 🌐 Multi-Domain: Route multiple domains with individual SSL certificates
- 🔁 Smart Redirects: Optional per-route HTTP→HTTPS redirects
- 🧩 Hot Reload: Live configuration updates without downtime
- 🛠️ CLI Management: Full-featured command-line interface
- 📊 Structured Logging: Configurable log levels for monitoring
- 🔌 Modular Library: Use as a library in your own projects
- 🎯 Path-Based Routing: Subroutes for complex routing scenarios
- 🔄 WebSocket Support: Full WebSocket proxying capability
Minipx is organized as a workspace with multiple components:
minipx/
├── cli/ # Command-line interface application
├── minipx/ # Core library (proxy, SSL, config management)
├── web/ # Web-based management interface (optional)
└── tools/ # Build and deployment tools
If you want to use minipx as a reverse proxy:
Installation:
# Linux (easy install)
sudo bash -c "$(curl -sSL https://raw.githubusercontent.com/Drew-Chase/minipx/master/cli/install.sh)" < /dev/tty
# Or build from source
git clone <repository-url>
cd minipx
cargo build --release -p minipx_cliBasic Usage:
# Run with auto-detected config
minipx
# With custom config and hot-reload
minipx --watch --config ./minipx.json
# Manage routes via CLI
minipx routes add api.example.com --host 127.0.0.1 --port 8080 --ssl📖 Full Documentation: CLI README
If you want to integrate minipx into your own Rust project:
Add to Cargo.toml:
[dependencies]
minipx = { path = "./minipx" }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }Example Usage:
use minipx::{config::Config, proxy, ssl_server};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::try_load("./minipx.json").await?;
config.watch_config_file();
tokio::try_join!(
proxy::start_rp_server(),
ssl_server::start_ssl_server()
)?;
Ok(())
}📖 Full Documentation: Library README
Watch a comprehensive tutorial on setting up and using minipx:
Minipx uses JSON configuration files for defining routes, SSL settings, and proxy behavior.
{
"email": "admin@example.com",
"cache_dir": "./ssl-cache",
"routes": {
"api.example.com": {
"host": "localhost",
"path": "/api/v1",
"port": 3000,
"ssl_enable": true,
"redirect_to_https": true
},
"*.example.com": {
"host": "192.168.1.100",
"port": 8080,
"ssl_enable": true,
"redirect_to_https": true
}
}
}Key Features:
- Wildcard domains: Use
*.example.comfor subdomain matching - Subroutes: Path-based routing to different backends
- Custom ports: Per-route listen ports for specialized services
- Hot reload: Changes apply automatically with
--watch
For detailed configuration options, see:
- Library Documentation - Configuration API and structure
- CLI Documentation - CLI-based configuration management
- HTTP Server (port 80): Handles plain HTTP traffic and redirects
- HTTPS Server (port 443): TLS termination with automatic certificates
- Custom Listeners: Additional ports per route for specialized services
- IPC Server: Local socket for CLI communication
- Automatic Provisioning: Certificates requested from Let's Encrypt
- TLS-ALPN-01 Validation: Served on port 443
- Multi-Domain: Individual certificates per domain
- Auto-Renewal: Handled transparently by rustls-acme
- Caching: Certificates cached in
cache_dirto avoid rate limits
- Request arrives on configured port
- Host header determines the route
- Path matching checks for subroutes
- Request proxied to backend with path rewriting
- WebSocket upgrades handled automatically
Route multiple web applications on different domains with automatic SSL.
Direct traffic to different microservices based on path or domain.
Hot-reload configuration for rapid development iteration.
Custom port routing for game servers and specialized protocols.
Path-based routing with SSL termination for API backends.
# Server management
minipx # Start with default config
minipx --watch --verbose # Start with hot-reload and logging
# Route management
minipx routes list # List all routes
minipx routes add example.com --port 8080 # Add new route
minipx routes update example.com --ssl # Enable SSL for route
minipx routes remove example.com # Remove route
# Configuration
minipx config show # Display current config
minipx config email admin@example.com # Set ACME emailSee CLI README for complete command reference.
- Ability to bind to port 80 (may require sudo/capabilities)
- Backend services running and accessible
- Domain names resolving to your server's public IP
- Port 443 accessible from the internet (for ACME validation)
- Valid email address for Let's Encrypt account
- Writable
cache_dirfor certificate storage
# Use sudo (quick solution)
sudo minipx --config /etc/minipx/config.json
# Or grant capabilities (Linux, persistent)
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/minipx- Verify domain DNS points to your server
- Ensure port 443 is open and accessible
- Check email is valid:
minipx config email your@email.com - Verify
cache_diris writable - Run with
--verboseto see detailed error messages
- Verify backend service is running:
curl http://localhost:8080 - Check route configuration:
minipx routes show example.com - Verify host/port are correct in config
minipx config show-path # Check which config is being used
minipx config show # View current configuration
minipx --verbose # Enable detailed loggingComplete command-line interface for running and managing minipx. Includes installation scripts, route management, and configuration tools.
Core library with modular components for configuration, proxy routing, SSL management, and IPC. Use in your own Rust projects.
Optional web-based management interface for visualizing and managing proxy routes (coming soon).
Build and deployment utilities for creating release archives and automating builds.
Minipx follows a modular architecture:
┌─────────────┐
│ CLI / App │ (Command line interface)
└──────┬──────┘
│
v
┌─────────────────────────────────────────┐
│ Minipx Core Library │
│ │
│ ┌────────┐ ┌───────┐ ┌──────────┐ │
│ │ Config │ │ Proxy │ │ SSL │ │
│ │ │ │ │ │ Server │ │
│ └────────┘ └───────┘ └──────────┘ │
│ │
│ ┌────────┐ ┌───────┐ │
│ │ IPC │ │ Utils │ │
│ └────────┘ └───────┘ │
└─────────────────────────────────────────┘
│ │
v v
┌──────────┐ ┌──────────┐
│ Backend │ │ Let's │
│ Services │ │ Encrypt │
└──────────┘ └──────────┘
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
# Clone repository
git clone <repository-url>
cd minipx
# Build all components
cargo build
# Build specific component
cargo build -p minipx # Library
cargo build -p minipx_cli # CLI
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run -p minipx_cli -- --verboseThis project is licensed under the MIT License — see the LICENSE file for details.
- Tokio — Async runtime
- Hyper — HTTP implementation
- Rustls — TLS implementation
- rustls-acme — Let's Encrypt integration
- Serde — Serialization framework
- Clap — CLI argument parsing
- Notify — File watching
- Caddy - Feature-rich web server with automatic HTTPS
- Traefik - Modern reverse proxy and load balancer
- Nginx - High-performance web server and proxy
Made with ❤️ using Rust