Automated Reverse Proxy Management for Docker Containers

Proxma is a powerful, Rust-based reverse proxy automation tool that automatically configures Nginx reverse proxy rules, manages SSL certificates, and handles DNS records for your Docker containers. Simply add labels to your containers, and Proxma takes care of the rest.

• Features
• How It Works
• Quick Start
• Installation
• Container Labels Reference
• Environment Variables
• Usage Examples
• Advanced Configuration
• Security Features
• Monitoring and Troubleshooting
• FAQ
• Development
• Contributing
• License
• Support

• 🔄 Automatic Nginx Configuration - Watches Docker containers and generates reverse proxy configurations
• 🔒 SSL Certificate Management - Automated Let's Encrypt and ZeroSSL certificate provisioning and renewal
• 🌐 DNS Integration - Automatic Cloudflare DNS record management
• 🔐 Authentication Support - Built-in HTTP Basic Authentication
• 🛡️ Security - Fail2ban integration for intrusion prevention
• 📊 Protocol Support - HTTP, HTTPS, gRPC proxying with proper status codes
• 🌐 HTTP/2 Support - Automatic HTTP/2 enablement for HTTPS connections
• 🔌 WebSocket Support - Built-in WebSocket proxying with proper headers
• ↩️ Domain Redirects - Flexible domain redirect management
• 🧹 Orphan Cleanup - Automatic removal of stale configurations
• 🌍 IDN Support - International domain names with Punycode conversion
• 🔐 Secure Password Hashing - bcrypt-based password authentication
• ⚡ High Performance - Rust-based for minimal resource usage
• 🎛️ Flexible Configuration - Container labels and environment variables
• 🔍 Debug Support - Comprehensive logging and debugging capabilities
• 📦 Queue Processing - Asynchronous task processing for reliability

Proxma operates as a Docker event listener that automatically manages your reverse proxy infrastructure:

1. Container Discovery - Monitors Docker events for containers with proxma.* labels
2. Configuration Generation - Creates optimized Nginx server blocks for each service
3. DNS Management - Automatically creates/updates DNS records (Cloudflare supported)
4. SSL Automation - Requests and manages certificates from Let's Encrypt or ZeroSSL
5. Security Integration - Configures fail2ban rules and authentication as needed
6. Cleanup - Removes configurations for stopped containers to prevent orphaned configs

graph TD
    A[Docker Container Start] --> B{Has proxma.hosts label?}
    B -->|Yes| C[Queue Processing]
    B -->|No| D[Ignore Container]
    C --> E[Generate Nginx Config]
    C --> F[Create DNS Records]
    C --> G[Request SSL Certificate]
    E --> H[Reload Nginx]
    F --> H
    G --> H
    H --> I[Service Available]

• Docker & Docker Compose - Container orchestration
• Domain names - Pointing to your server's IP address
• Ports 80 & 443 - Available for HTTP/HTTPS traffic
• Cloudflare account (optional) - For automated DNS management
• Email address - For SSL certificate registration

• Memory: 512MB RAM minimum (1GB recommended)
• CPU: 1 CPU core minimum
• Storage: 1GB for configurations and certificates
• Network: Internet access for certificate validation

1. Create a docker-compose.yml file:

services:
  proxma:
    image: dublok/proxma:latest
    container_name: proxma
    ports:
      - "80:80"
      - "443:443"
    environment:
      - PROXMA_SSL=true
      - [email protected]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - proxma_conf:/etc/nginx/conf.d
      - certificates:/etc/certificates
    restart: always

  # Example application
  myapp:
    image: nginx:alpine
    container_name: myapp
    labels:
      proxma.hosts: "myapp.example.com"
      proxma.port: "80"
    restart: always

volumes:
  proxma_conf:
  certificates:

2. Start the services:

docker-compose up -d

3. That's it! Proxma will automatically:
   • Create an Nginx reverse proxy configuration for myapp.example.com
   • Request an SSL certificate from Let's Encrypt
   • Configure secure HTTPS proxying

docker run -d \
  --name proxma \
  -p 80:80 \
  -p 443:443 \
  -e PROXMA_SSL=true \
  -e [email protected] \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v proxma_conf:/etc/nginx/conf.d \
  -v certificates:/etc/certificates \
  --restart always \
  dublok/proxma:latest

git clone https://github.com/ercindedeoglu/proxma.git
cd proxma
docker build -t proxma:local .
# Use proxma:local in your docker-compose.yml

Configure your containers using these labels:

Support for per-host port, protocol, and DNS settings:

labels:
  # Format: domain:port:protocol:proxied
  proxma.hosts: "api.example.com:8080:http:false,grpc.example.com:9000:grpc:true"

Configure Proxma globally using environment variables:

Note: Currently only Let's Encrypt is fully implemented. ZeroSSL support is planned for future releases.

Note: ZeroSSL support and additional SSL providers are planned features based on configuration examples found in the codebase.

services:
  webapp:
    image: nginx:alpine
    labels:
      proxma.hosts: "mysite.com,www.mysite.com"
      proxma.port: "80"
      proxma.redirects: "mysite.com>www.mysite.com"

services:
  api:
    image: myapi:latest
    labels:
      proxma.hosts: "api.example.com:8080:http,grpc.example.com:9000:grpc"

services:
  admin:
    image: admin-panel:latest
    labels:
      proxma.hosts: "admin.example.com"
      proxma.port: "3000"
      proxma.ssl: "true"
      proxma.auth: "true"
      proxma.auth.username: "admin"
      proxma.auth.password: "secure-password"

services:
  proxma:
    image: dublok/proxma:latest
    environment:
      - PROXMA_SSL=true
      - [email protected]
      - PROXMA_SSL_STAGING=false  # Production certificates
      - PROXMA_DNS_PROVIDER=cloudflare
      - PROXMA_DNS_TARGET=server.example.com
      - PROXMA_CLOUDFLARE_API_TOKEN=your-token-here
    # ... volumes and ports

  frontend:
    image: frontend:latest
    labels:
      proxma.hosts: "app.example.com"
      proxma.port: "80"
      proxma.dns.proxied: "true"

  api:
    image: api:latest
    labels:
      proxma.hosts: "api.example.com"
      proxma.port: "3000"
      proxma.auth: "true"
      proxma.auth.username: "apiuser"
      proxma.auth.password: "apipass"

services:
  proxma:
    image: dublok/proxma:latest
    container_name: proxma
    ports:
      - "80:80"
      - "443:443"
    environment:
      # SSL Configuration
      - PROXMA_SSL=true
      - [email protected]
      - PROXMA_SSL_STAGING=false
      - PROXMA_SSL_PROVIDER=letsencrypt
      
      # DNS Configuration
      - PROXMA_DNS_PROVIDER=cloudflare
      - PROXMA_DNS_TARGET=your-server.yourdomain.com
      - PROXMA_DNS_TYPE=CNAME
      - PROXMA_DNS_PROXIED=true
      
      # Cloudflare Credentials
      - PROXMA_CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
      
      # Security
      - PROXMA_DISABLE_FAIL2BAN=false
      
      # Web Server Defaults
      - PROXMA_WEBSERVER_CLIENT_MAX_BODY_SIZE=10m
      - PROXMA_WEBSERVER_PROXY_READ_TIMEOUT=300s
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - proxma_conf:/etc/nginx/conf.d
      - certificates:/etc/certificates
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    restart: always
    
volumes:
  proxma_conf:
  certificates:

Proxma generates optimized Nginx configurations with advanced features:

labels:
  proxma.hosts: "myapp.example.com"
  proxma.port: "8080"
  proxma.webserver.client_max_body_size: "50m"  # Allow large uploads
  proxma.webserver.proxy_read_timeout: "300s"   # 5-minute timeout
  proxma.webserver.proxy_connect_timeout: "10s" # Quick connection timeout

Generated Nginx Features:

• HTTP/2 automatically enabled for HTTPS
• WebSocket support with proper connection upgrades
• gRPC support with error handling and status codes
• Modern SSL with TLSv1.2/TLSv1.3 protocols only
• Comprehensive headers for upstream compatibility
• ACME challenges for certificate validation
• Security headers and proper authentication handling

Proxma includes built-in fail2ban configuration to protect against:

• HTTP authentication brute force attacks
• Nginx probe attempts
• HTTP error rate limiting

Disable with: PROXMA_DISABLE_FAIL2BAN=true

Support for HTTP Basic Authentication per container:

labels:
  proxma.auth: "true"
  proxma.auth.username: "secure-user"
  proxma.auth.password: "strong-password"
  proxma.auth.realm: "Protected Application"

• Automatic certificate provisioning and renewal
• Let's Encrypt support (ZeroSSL planned for future releases)
• Staging environment support for testing
• Modern SSL protocols - TLSv1.2 and TLSv1.3 only
• HTTP/2 automatic enablement on HTTPS connections
• ACME challenge handling for certificate validation

• gRPC Error Handling - Proper gRPC status codes (UNAUTHENTICATED, UNAVAILABLE, etc.)
• WebSocket Support - Automatic WebSocket proxying with connection upgrades
• International Domains - IDN support with automatic Punycode conversion
• Comprehensive Headers - Full proxy header forwarding for upstream compatibility
• Password Security - bcrypt hashing for authentication credentials

Monitor Proxma activity:

# View Proxma logs
docker logs proxma

# Follow logs in real-time
docker logs -f proxma

# View nginx logs
docker exec proxma tail -f /var/log/nginx/access.log
docker exec proxma tail -f /var/log/nginx/error.log

Check if services are properly configured:

# List generated nginx configurations
docker exec proxma ls -la /etc/nginx/conf.d/

# Check nginx configuration syntax
docker exec proxma nginx -t

# View certificate status
docker exec proxma ls -la /etc/certificates/

Certificate generation fails:

• Verify domain DNS points to your server
• Check PROXMA_SSL_EMAIL is set
• Try staging mode first: PROXMA_SSL_STAGING=true

Nginx configuration errors:

• Check container labels are properly formatted
• Verify port numbers are valid
• Review Proxma logs for specific errors

DNS records not created:

• Verify Cloudflare credentials
• Check domain exists in Cloudflare
• Ensure API token has DNS edit permissions

Q: What makes Proxma different from Traefik or Nginx Proxy Manager? A: Proxma is written in Rust for performance, focuses specifically on Docker label-based configuration, and includes built-in DNS management and fail2ban security out of the box.

Q: Can I use Proxma with existing Nginx configurations? A: Proxma manages configurations in /etc/nginx/conf.d/ with the prefix proxma_. Your existing configurations in other locations won't be affected.

Q: Does Proxma support IPv6? A: Yes, Proxma supports IPv6 automatically when your Docker setup and DNS records are configured for IPv6.

Q: How do I use production SSL certificates instead of staging? A: Set PROXMA_SSL_STAGING=false or use the label proxma.ssl.staging: "false"

Q: Can I use my own SSL certificates? A: Currently, Proxma only supports automated certificate provisioning. Manual certificate support is planned for future releases.

Q: What SSL providers are supported? A: Let's Encrypt (default) and ZeroSSL. Set via PROXMA_SSL_PROVIDER or proxma.ssl.provider.

Q: Do I need Cloudflare for Proxma to work? A: No, Cloudflare is only needed for automatic DNS record management. You can manually manage DNS and still use Proxma for reverse proxy and SSL.

Q: Can I use other DNS providers besides Cloudflare? A: Currently only Cloudflare is supported. Route53 support is in development.

Q: How do I handle containers that use non-standard ports? A: Use the format proxma.hosts: "domain.com:8080" or set a global proxma.port: "8080"

Q: Can I proxy to external services (non-Docker)? A: Not directly. Proxma is designed for Docker containers. For external services, create a simple Docker container that proxies to the external service.

Q: How do I handle WebSocket connections? A: Proxma automatically configures Nginx for WebSocket support with proper Upgrade and Connection headers. No additional configuration needed.

Q: Does Proxma support HTTP/2? A: Yes, HTTP/2 is automatically enabled for all HTTPS connections using the http2 on; directive.

Q: How does gRPC error handling work? A: Proxma provides proper gRPC status codes for errors: UNAUTHENTICATED (16), UNAVAILABLE (14), DEADLINE_EXCEEDED (4), and UNIMPLEMENTED (12) with HTTP 200 responses as required by gRPC specification.

Q: Can I use international domain names? A: Yes, Proxma supports IDN (International Domain Names) and automatically converts them to Punycode for ASCII compatibility.

Q: Why isn't my container being detected? A: Ensure the container has the proxma.hosts label. Check docker logs proxma for any error messages.

Q: Certificates aren't being generated. What's wrong? A: Verify: 1) Domain DNS points to your server, 2) PROXMA_SSL_EMAIL is set, 3) Ports 80/443 are accessible from the internet, 4) Check if you're hitting Let's Encrypt rate limits.

Q: How do I enable debug logging? A: Set PROXMA_DEBUG=true in your environment variables to get detailed logging output.

Q: What are the default authentication credentials? A: Default username is root and password is root. Always change these in production!

Q: How do I migrate from another reverse proxy solution? A: 1) Stop your existing reverse proxy, 2) Add Proxma labels to containers, 3) Start Proxma. It will automatically configure everything.

• CPU: ~1-5% on a modern CPU under normal load
• Memory: ~50-200MB depending on the number of configured domains
• Disk I/O: Minimal, mainly during certificate generation and nginx reloads

• Single Instance: Handles hundreds of domains efficiently
• Certificate Limits: Let's Encrypt has rate limits (50 certificates per week per domain)
• Nginx Performance: Inherits Nginx's excellent performance characteristics
• Queue Processing: Built-in queue system prevents overwhelming external APIs

# Add health checks to your docker-compose.yml
services:
  proxma:
    # ... other configuration
    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 10s
      retries: 3

Queue Processing System:

• Nginx Queue - Handles configuration generation and reloads
• Certificate Queue - Manages SSL certificate requests asynchronously
• Orphan Cleanup - Removes stale configurations after container stops
• Rate Limiting - Prevents overwhelming external APIs (DNS, SSL providers)

Configuration Generation:

• Domain Sanitization - Converts domains to filesystem-safe names
• Template System - Modular Nginx configuration generation
• Authentication - bcrypt password hashing with htpasswd files
• Protocol Detection - Automatic HTTP/gRPC/WebSocket handling

# Clone the repository
git clone https://github.com/ercindedeoglu/proxma.git
cd proxma

# Build the Docker image
docker build -t proxma .

# Run with development settings
docker-compose -f docker-compose.dev.yml up

src/
├── main.rs              # Application entry point
├── docker.rs            # Docker API integration
├── nginx/               # Nginx configuration management
├── dns/                 # DNS provider integrations
├── certbot.rs           # Certificate management
├── queue/               # Task queue system
└── models/              # Data structures

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Install Rust: https://rustup.rs/
2. Clone the repository
3. Run cargo build to compile
4. Run cargo test to execute tests

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

• Nginx - High-performance web server and reverse proxy
• Let's Encrypt - Free SSL certificates
• Cloudflare - DNS and CDN services
• Docker - Containerization platform

• Issues: GitHub Issues
• Docker Hub: dublok/proxma
• Documentation: Project Documentation

Made with ❤️ in Rust