manhpv151090/https repository overview

⁠HTTPS Reverse Proxy - Github⁠

A lightweight, high-performance HTTPS reverse proxy written in Rust. Designed for local development with Docker Compose to easily route traffic to multiple backend services with automatic self-signed TLS certificates.

⁠📚 Table of Contents

• Features⁠
• Prerequisites⁠
• Quick Start⁠
• Configuration⁠
  • Routes Configuration⁠
  • Environment Variables⁠
• Development⁠
  • Project Structure⁠
  • Running Locally⁠
  • Building Docker Image⁠
  • Running Tests⁠
• Certificates⁠
  • Auto-Generated CA Certificate⁠
  • Trusting the CA Certificate⁠
  • Uninstall CA⁠
  • Manual Import⁠
• Troubleshooting⁠
• License⁠

⁠🚀 Features

• ✅ Port-based Routing: Map specific ports to different backend services easily.
• ✅ HTTPS Upstream: Supports proxying to external HTTPS targets (e.g., public APIs).
• ✅ WebSocket Support: Full bidirectional WebSocket tunneling (wss:// -> ws://).
• ✅ Auto TLS: Automatically generates self-signed CA and server certificates on startup.
• ✅ Zero Config: Works out-of-the-box with Docker Compose.
• ✅ Streaming: Non-buffering body forwarding for high performance.
• ✅ Tiny Footprint: Alpine-based Docker image (~7MB).

⁠🛠 Prerequisites

• Docker⁠
• Docker Compose⁠

⁠⚡ Quick Start

⁠1. Configure Listeners

Create a routes.yaml file to define your routing rules:

listeners:
  - port: 440
    target: http://api:3000 # Local API service
  - port: 441
    target: http://app:3001 # Local Web App
  - port: 442
    target: https://httpbin.org # External HTTPS service
  - port: 443
    target: http://ws-echo:8080 # WebSocket service

⁠2. Update docker-compose.yml

Add the proxy service to your composition:

services:
  proxy:
    image: manhpv151090/https:latest
    platform: linux/amd64
    ports:
      - "440:440"
      - "441:441"
      - "442:442"
      - "443:443"
    volumes:
      - ./routes.yaml:/etc/proxy/routes.yaml:ro
      - ./certs:/certs

⁠3. Run the Proxy

docker compose up --build

⁠4. Verify

• HTTPS Request:

  curl -k https://localhost:440/
  

  Copy
• WebSocket Connection:

  wscat -n -c wss://localhost:443/ws
  

  Copy

⁠⚙️ Configuration

⁠Routes Configuration

The routes.yaml file supports the following structure:

listeners:
  - port: <LISTENING_PORT>
    target: <UPSTREAM_URL>

• port: The port on the proxy container that will accept incoming HTTPS connections.
• target: The upstream URL where requests will be forwarded. Supports http://, https://, and ws://.

⁠Environment Variables

⁠💻 Development

⁠Project Structure

.
├── proxy/                    # HTTPS reverse proxy crate
│   ├── src/
│   │   ├── main.rs           # Entry point, server setup
│   │   ├── lib.rs            # Library exports
│   │   ├── config.rs         # YAML config loading
│   │   ├── proxy.rs          # Core proxy logic, WebSocket handling
│   │   └── tls.rs            # TLS configuration
│   ├── tests/
│   │   └── integration_test.rs
│   └── Cargo.toml
├── manage-ca/                # CA certificate management CLI
│   ├── src/
│   │   └── main.rs           # CLI entry point + NSS/browser cert management
│   └── Cargo.toml
├── Cargo.toml                # Workspace manifest
├── Dockerfile                # Multi-stage Docker build
├── entrypoint.sh             # Docker entrypoint (CA + cert generation)
├── docker-compose.yml        # Example composition with demo services
├── routes.yaml               # Example routes config
└── LICENSE

⁠Running Locally (Rust)

If you have Rust installed, you can run the project natively:

1. Install Rust:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   Copy
2. Run:

   cargo run --release
   

   Copy

⁠Building Docker Image

To build the Docker image locally:

docker build -t my-https-proxy .

⁠Running Tests

cargo test --all-features

⁠🔐 Certificates

⁠Auto-Generated CA Certificate

By default, the container automatically generates a Certificate Authority (CA) and server certificates on startup. The CA certificate is stored in the certs/ca/ directory.

Important: Make sure to mount the certs directory in your docker-compose.yml:

volumes:
  - ./routes.yaml:/etc/proxy/routes.yaml:ro
  - ./certs:/certs

⁠Trusting the CA Certificate

To avoid browser security warnings, use the manage-ca CLI tool to install the CA certificate.

Prerequisites:

# Ubuntu/Debian
sudo apt install libnss3-tools

# Fedora/RHEL
sudo dnf install nss-tools

# Arch
sudo pacman -S nss

Option 1: Download from GitHub Releases

Linux:

curl -L -o manage-ca https://github.com/manhpham90vn/https/releases/latest/download/manage-ca-linux-amd64
chmod +x manage-ca
sudo ./manage-ca install

macOS:

# Intel
curl -L -o manage-ca https://github.com/manhpham90vn/https/releases/latest/download/manage-ca-macos-amd64
# Apple Silicon
curl -L -o manage-ca https://github.com/manhpham90vn/https/releases/latest/download/manage-ca-macos-arm64

chmod +x manage-ca
sudo ./manage-ca install

Windows (PowerShell as Administrator):

Invoke-WebRequest -Uri "https://github.com/manhpham90vn/https/releases/latest/download/manage-ca-windows-amd64.exe" -OutFile manage-ca.exe
.\manage-ca.exe install

Option 2: Build from source

cargo build --release -p manage-ca
sudo ./target/release/manage-ca install     # Linux/macOS
.\target\release\manage-ca.exe install      # Windows (as Admin)

Custom cert path:

sudo ./manage-ca install --cert /path/to/ca.crt

After installation, restart your browsers.

⁠Uninstall CA

sudo ./manage-ca uninstall          # Linux/macOS
.\manage-ca.exe uninstall           # Windows (as Admin)

⁠Manual Import (alternative)

If you prefer not to use manage-ca, you can import the certificate manually.

Linux (Ubuntu/Debian):

sudo cp certs/ca/ca.crt /usr/local/share/ca-certificates/local-dev-ca.crt
sudo update-ca-certificates

Linux (Fedora/RHEL/Arch):

sudo cp certs/ca/ca.crt /etc/pki/ca-trust/source/anchors/local-dev-ca.crt
sudo update-ca-trust extract

Chrome/Chromium/Edge:

1. Go to chrome://certificate-manager
2. Under Custom, click Installed by you
3. In Trusted Certificates section, click Import
4. Select certs/ca/ca.crt

Firefox:

1. Go to about:preferences#privacy
2. Scroll to Certificates → View Certificates → Authorities → Import
3. Select certs/ca/ca.crt
4. Check ✓ "Trust this CA to identify websites"

macOS (manual):

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain certs/ca/ca.crt

Windows (manual):

certutil -addstore Root certs\ca\ca.crt

⁠❓ Troubleshooting

Port Conflicts: If a port is already in use on your host, change the mapping in docker-compose.yml (e.g., "8443:443" maps host port 8443 to container port 443).

Certificate Errors: Since self-signed certificates are used by default, browsers and tools like curl will warn about security.

• Browser: Accept the security risk (usually under "Advanced").
• curl: Use the -k or --insecure flag.

⁠📄 License

This project is open source and available under the MIT License⁠.