go-proxy

A lightweight, easy-to-use, and efficient reverse proxy and load balancer with a web UI.

Table of content

• Key Points
• Getting Started
  • Commands
  • Environment variables
  • Use JSON Schema in VSCode
  • Config File
  • Provider File
• Known issues
• Build it yourself

Key Points

• Easy to use
• Auto certificate obtaining and renewal (See Supported DNS Challenge Providers)
• Auto configuration for docker contaienrs
• Auto hot-reload on container state / config file changes
• Support HTTP(s), TCP and UDP
• Support HTTP(s) round robin load balancing
• Web UI for configuration and monitoring (See screenshots)
• Written in Go

🔼Back to top

Getting Started

1. Setup DNS Records

   • A Record: *.y.z -> 10.0.10.1
   • AAAA Record: *.y.z -> ::ffff:a00:a01

2. Start go-proxy

   • Binary / systemd service
   • Docker

3. Configure go-proxy

   • with text editor (i.e. Visual Studio Code)
   • or with web config editor via http://ip:8080

🔼Back to top

Commands

• go-proxy start proxy server
• go-proxy validate validate config and exit
• go-proxy reload trigger a force reload of config

For docker containers, run docker exec -it go-proxy /app/go-proxy <command>

Environment variables

Booleans:

• GOPROXY_DEBUG enable debug behaviors
• GOPROXY_NO_SCHEMA_VALIDATION: disable schema validation (useful for testing new DNS Challenge providers)

Use JSON Schema in VSCode

Copy .vscode/settings.example.json to .vscode/settings.json and modify it to fit your needs

🔼Back to top

Config File

See config.example.yml for more

# autocert configuration
autocert:
  email: # ACME Email
  domains: # a list of domains for cert registration
  provider: # DNS Challenge provider
  options: # provider specific options
    - ...
# reverse proxy providers configuration
providers:
  entry_1:
    kind: docker
    value: # `FROM_ENV` or full url to docker host
  entry_2:
    kind: file
    value: # relative path of file to `config/`

🔼Back to top

Provider File

Fields are same as docker labels starting from scheme

See providers.example.yml for examples

🔼Back to top

Known issues

• Cert "renewal" is actually obtaining a new cert instead of renewing the existing one

🔼Back to top

Build it yourself

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

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

3. get dependencies with make get

4. build binary with make build

5. start your container with make up (docker) or bin/go-proxy (binary)

🔼Back to top