Deploying Zoraxy

Introduction

Zoraxy is a modern, user-friendly reverse proxy and application gateway with automatic HTTPS certificate management. It provides an intuitive web-based interface for routing traffic to your applications without requiring manual configuration file editing.

Built with simplicity in mind, Zoraxy makes complex networking tasks accessible to users of all skill levels. It combines the power of a full-featured reverse proxy with the ease of a graphical management interface.

Key highlights of Zoraxy:

• Web-Based Management: Configure everything through a clean, modern UI
• Automatic HTTPS: Let’s Encrypt integration for automatic certificate management
• Virtual Hosts: Route traffic based on domain names
• Load Balancing: Distribute traffic across multiple backends
• WebSocket Support: Full WebSocket proxying capabilities
• Access Control: IP whitelisting and blacklisting
• Subdomain Routing: Easy subdomain to service mapping
• Docker Integration: Automatic service discovery for Docker containers
• Statistics Dashboard: Real-time traffic monitoring and analytics
• Authentication: Built-in basic auth and forward auth support
• Global Area Network: Mesh networking between Zoraxy instances
• Custom Headers: Add or modify HTTP headers

This guide walks through deploying Zoraxy on Klutch.sh using Docker, enabling you to manage your reverse proxy through an intuitive web interface.

Why Deploy Zoraxy on Klutch.sh

Deploying Zoraxy on Klutch.sh provides several advantages for traffic management:

Centralized Routing: Manage all your application routing from a single, user-friendly interface.

Automatic HTTPS: Combined with Klutch.sh’s infrastructure, ensure all traffic is encrypted.

Simplified Configuration: No need to edit nginx or Traefik configuration files manually.

Real-Time Monitoring: View traffic statistics and analytics through the dashboard.

Persistent Configuration: Your proxy rules and certificates persist across deployments.

GitHub Integration: Store your Zoraxy configuration in version control.

Prerequisites

Before deploying Zoraxy on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic understanding of Docker and containerization
• Understanding of reverse proxy concepts and HTTP routing
• (Optional) Domain names for virtual host routing

Understanding Zoraxy Architecture

Zoraxy provides several routing mechanisms:

Virtual Hosts: Route traffic based on the Host header to different backends.

Subdomain Routing: Map subdomains to specific services automatically.

Path-Based Routing: Route different URL paths to different backends.

Load Balancer: Distribute requests across multiple upstream servers.

WebSocket Proxy: Handle WebSocket upgrades and maintain connections.

Preparing Your Repository

Create a GitHub repository for your Zoraxy deployment.

Repository Structure

zoraxy-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Zoraxy:

FROM zoraxydocker/zoraxy:latest

# Set environment variables
ENV ZORAXY_PORT=:8000
ENV ZORAXY_NOAUTH=false

# Create directories for persistent data
RUN mkdir -p /opt/zoraxy/config \
    && mkdir -p /opt/zoraxy/certs

# Expose ports
# Management interface
EXPOSE 8000
# HTTP traffic
EXPOSE 80
# HTTPS traffic
EXPOSE 443

# Volume for configuration
VOLUME ["/opt/zoraxy/config"]

# Start Zoraxy
ENTRYPOINT ["./zoraxy"]
CMD ["-port=:8000"]

Environment Variables Reference

Variable	Required	Default	Description
ZORAXY_PORT	No	:8000	Management interface port
ZORAXY_NOAUTH	No	false	Disable authentication (not recommended)
ZORAXY_FASTGEOIP	No	false	Enable fast GeoIP lookup
ZORAXY_SSHLB	No	false	Enable SSH load balancing

Deploying Zoraxy on Klutch.sh

Push Your Repository to GitHub

Initialize and push your configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “zoraxy” or “reverse-proxy”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP for the management interface:

• Select HTTP as the traffic type
• Set the internal port to 8000

Attach Persistent Volumes

Add storage for configuration and certificates:

Mount Path	Recommended Size	Purpose
/opt/zoraxy/config	1 GB	Zoraxy configuration and rules
/opt/zoraxy/certs	1 GB	SSL certificates

Deploy Your Application

Click Deploy to build and start Zoraxy.

Access Management Interface

Once deployment completes, access Zoraxy at https://your-app-name.klutch.sh.

Initial Configuration

First-Time Setup

1. Navigate to your Zoraxy management URL
2. Create an admin account with a secure password
3. Log in to access the dashboard

Dashboard Overview

The Zoraxy dashboard provides:

• Status: Overview of running services and traffic
• Proxy Rules: Configure virtual hosts and routing
• Certificates: Manage SSL/TLS certificates
• Access Control: IP-based access rules
• Statistics: Traffic analytics and monitoring

Configuring Proxy Rules

Adding a Virtual Host

1. Navigate to Proxy Rules
2. Click “Add Proxy Rule”
3. Configure:
   • Matching URL: Domain or subdomain to match
   • Destination: Backend server URL
   • Enable TLS: Use HTTPS for backend
4. Save and test the rule

Subdomain Routing

Map subdomains to services:

1. Add a wildcard DNS record for your domain
2. Create rules for each subdomain
3. Configure backend destinations

Path-Based Routing

Route different paths to different backends:

1. Create a proxy rule with path prefix
2. Configure stripping or preserving the path
3. Set up multiple rules for different paths

Certificate Management

Automatic Certificates

Enable Let’s Encrypt:

1. Navigate to Certificates
2. Enable automatic certificate renewal
3. Configure email for notifications
4. Request certificates for your domains

Custom Certificates

Upload existing certificates:

1. Navigate to Certificates
2. Click “Upload Certificate”
3. Provide certificate and private key
4. Assign to proxy rules

Access Control

IP Whitelisting

Restrict access to specific IPs:

1. Navigate to Access Control
2. Add allowed IP ranges
3. Enable whitelist mode
4. Apply to specific rules or globally

IP Blacklisting

Block malicious IPs:

1. Navigate to Access Control
2. Add blocked IP ranges
3. Enable blacklist
4. Configure blocking response

Authentication

Add basic authentication:

1. Navigate to proxy rule settings
2. Enable Basic Auth
3. Create username and password
4. Clients will be prompted for credentials

Load Balancing

Configuring Multiple Backends

Set up load balancing:

1. Create a proxy rule
2. Add multiple destination URLs
3. Configure load balancing algorithm
4. Enable health checks

Load Balancing Algorithms

• Round Robin: Distribute evenly
• Random: Random selection
• IP Hash: Consistent routing by client IP

Troubleshooting Common Issues

Proxy Rule Not Working

Solutions:

• Verify the matching URL is correct
• Check backend server is accessible
• Review proxy rule configuration
• Check for conflicting rules

Certificate Errors

Solutions:

• Verify domain DNS is correctly configured
• Check certificate hasn’t expired
• Review Let’s Encrypt rate limits
• Ensure port 80 is accessible for HTTP challenge

WebSocket Connection Failing

Solutions:

• Enable WebSocket support in proxy rule
• Check backend WebSocket configuration
• Review timeout settings

Additional Resources

• Zoraxy Official Website
• Zoraxy GitHub Repository
• Zoraxy Docker Hub

Conclusion

Deploying Zoraxy on Klutch.sh gives you a modern, user-friendly reverse proxy with a powerful web-based management interface. Whether you need simple domain routing, load balancing, or automatic HTTPS certificates, Zoraxy provides the features of enterprise reverse proxies in an accessible package.