A lightweight, simple, and performant reverse proxy with WebUI.

Website | Wiki | Discord

EN | 中文

Have questions? Ask ChatGPT! (Thanks to @ismesid)

Table of content

• Table of content
• Running demo
• Key Features
• Prerequisites
• Setup
• How does GoDoxy work
• Proxmox Integration
  • Automatic Route Binding
  • WebUI Management
  • API Endpoints
• Update / Uninstall system agent
• Screenshots
  • idlesleeper
  • Metrics and Logs
• Manual Setup
  • Folder structrue
• Build it yourself
• Star History

Running demo

https://demo.godoxy.dev

Key Features

• Simple
  • Effortless configuration with simple labels or WebUI
  • Simple multi-node setup
  • Detailed error messages for easy troubleshooting.
• ACL: connection / request level access control
  • IP/CIDR
  • Country (Maxmind account required)
  • Timezone (Maxmind account required)
  • Access logging
  • Periodic notification of access summaries for number of allowed and blocked connections
• Advanced Automation
  • Automatic SSL certificate management with Let's Encrypt (using DNS-01 Challenge)
  • Auto-configuration for Docker containers
  • Hot-reloading of configurations and container state changes
• Container Runtime Support
  • Docker
  • Podman
• Idle-sleep: stop and wake containers based on traffic (see screenshots)
  • Docker containers
  • Proxmox LXC containers
• Proxmox Integration
  • Automatic route binding: Routes automatically bind to Proxmox nodes or LXC containers by matching hostname, IP, or alias
  • LXC lifecycle control: Start, stop, restart containers directly from WebUI
  • Real-time logs: Stream journalctl logs from nodes and LXC containers via WebSocket
• Traffic Management
  • HTTP reserve proxy
  • TCP/UDP port forwarding
  • OpenID Connect support: SSO and secure your apps easily
  • ForwardAuth support: integrate with any auth provider (e.g. TinyAuth)
• Customization
  • HTTP middlewares
  • Custom error pages support
• Web UI
  • App Dashboard
  • Config Editor
  • Uptime and System Metrics
  • Docker
    • Container lifecycle management (start, stop, restart)
    • Real-time container logs via WebSocket
  • Proxmox
    • LXC container lifecycle management (start, stop, restart)
    • Real-time node and LXC journalctl logs via WebSocket
• Cross-Platform support
  • Supports linux/amd64 and linux/arm64
• Efficient and Performant
  • Written in Go

Prerequisites

Configure Wildcard DNS Record(s) to point to machine running GoDoxy, e.g.

• A Record: *.domain.com -> 10.0.10.1
• AAAA Record (if you use IPv6): *.domain.com -> ::ffff:a00:a01

Setup

Note

GoDoxy is designed to be running in host network mode, do not change it.

To change listening ports, modify .env.

1. Prepare a new directory for docker compose and config files.

2. Run setup script inside the directory, or set up manually

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/yusing/godoxy/main/scripts/setup.sh)"
   

3. Start the docker compose service from generated compose.yml:

   docker compose up -d
   

4. You may now do some extra configuration on WebUI https://godoxy.yourdomain.com

How does GoDoxy work

1. List all the containers
2. Read container name, labels and port configurations for each of them
3. Create a route if applicable (a route is like a "Virtual Host" in NPM)
4. Watch for container / config changes and update automatically

Note

GoDoxy uses the label proxy.aliases as the subdomain(s), if unset it defaults to the container_name field in docker compose.

For example, with the label proxy.aliases: qbt you can access your app via qbt.domain.com.

Proxmox Integration

GoDoxy can automatically discover and manage Proxmox nodes and LXC containers through configured providers.

Automatic Route Binding

Routes are automatically linked to Proxmox resources through reverse lookup:

1. Node-level routes (VMID = 0): When hostname, IP, or alias matches a Proxmox node name or IP
2. Container-level routes (VMID > 0): When hostname, IP, or alias matches an LXC container

This enables seamless proxy configuration without manual binding:

routes:
  pve-node-01:
    host: pve-node-01.internal
    port: 8006
    # Automatically links to Proxmox node pve-node-01

WebUI Management

From the WebUI, you can:

• LXC Lifecycle Control: Start, stop, restart containers
• Node Logs: Stream real-time journalctl output from nodes
• LXC Logs: Stream real-time journalctl output from containers

API Endpoints

# Node journalctl (WebSocket)
GET /api/v1/proxmox/journalctl/:node

# LXC journalctl (WebSocket)
GET /api/v1/proxmox/journalctl/:node/:vmid

# LXC lifecycle control
POST /api/v1/proxmox/lxc/:node/:vmid/start
POST /api/v1/proxmox/lxc/:node/:vmid/stop
POST /api/v1/proxmox/lxc/:node/:vmid/restart

Update / Uninstall system agent

Update:

bash -c "$(curl -fsSL https://github.com/yusing/godoxy/raw/refs/heads/main/scripts/install-agent.sh)" -- update

Uninstall:

bash -c "$(curl -fsSL https://github.com/yusing/godoxy/raw/refs/heads/main/scripts/install-agent.sh)" -- uninstall

Screenshots

idlesleeper

Metrics and Logs

Routes	Servers

Manual Setup

1. Make config directory then grab config.example.yml into config/config.yml

   mkdir -p config && wget https://raw.githubusercontent.com/yusing/godoxy/main/config.example.yml -O config/config.yml

2. Grab .env.example into .env

   wget https://raw.githubusercontent.com/yusing/godoxy/main/.env.example -O .env

3. Grab compose.example.yml into compose.yml

   wget https://raw.githubusercontent.com/yusing/godoxy/main/compose.example.yml -O compose.yml

Folder structrue

├── certs
│   ├── cert.crt
│   └── priv.key
├── compose.yml
├── config
│   ├── config.yml
│   ├── middlewares
│   │   ├── middleware1.yml
│   │   ├── middleware2.yml
│   ├── provider1.yml
│   └── provider2.yml
├── data
│   ├── metrics # metrics data
│   │   ├── uptime.json
│   │   └── system_info.json
└── .env

Build it yourself

1. Clone the repository git clone https://github.com/yusing/godoxy --depth=1

2. Install / Upgrade go (>=1.22) and make if not already

3. Clear cache if you have built this before (go < 1.22) with go clean -cache

4. get dependencies with make get

5. build binary with make build

Star History

🔼Back to top