Skip to content
Klutch.sh Docs

Deploying go-doxy

Introduction

go-doxy is a lightweight, Docker-aware reverse proxy written in Go. It automatically discovers Docker containers and routes HTTP traffic based on labels, eliminating the need for manual proxy configuration when containers are added or removed.

Designed for simplicity, go-doxy provides essential reverse proxy features without the complexity of larger solutions. It is particularly well-suited for development environments and small deployments where automatic service discovery is valuable.

Key highlights of go-doxy:

  • Docker Integration: Automatic container discovery via Docker socket
  • Label-Based Routing: Configure routing through container labels
  • Lightweight: Minimal resource footprint
  • Hot Reload: Automatically updates when containers change
  • TLS Support: Optional HTTPS termination
  • Simple Configuration: Minimal setup required
  • Fast: Written in Go for performance
  • Health Checking: Monitor backend container health
  • WebSocket Support: Proxy WebSocket connections
  • Open Source: Community-driven development

This guide walks through deploying go-doxy on Klutch.sh using Docker.

Why Deploy go-doxy on Klutch.sh

While Klutch.sh provides built-in routing, go-doxy can be useful for:

Multi-Container Routing: Route between multiple containers in a deployment.

Development Environments: Mirror production proxy setups in development.

Custom Routing Logic: Implement specific routing requirements.

Service Mesh: Create internal service communication layer.

Prerequisites

Before deploying go-doxy on Klutch.sh, ensure you have:

Understanding go-doxy Architecture

go-doxy operates as a single process:

Docker Client: Connects to Docker socket to watch for container events.

Route Manager: Maintains routing table based on container labels.

HTTP Server: Receives requests and forwards to appropriate backends.

Health Checker: Monitors backend container availability.

Preparing Your Repository

Create a GitHub repository with your go-doxy configuration.

Repository Structure

go-doxy-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

FROM golang:alpine AS builder


RUN apk add --no-cache git


# Build go-doxy from source
WORKDIR /build
RUN git clone https://github.com/yusing/go-proxy.git . && \
    go build -o go-doxy .


FROM alpine:latest


RUN apk add --no-cache ca-certificates


COPY --from=builder /build/go-doxy /usr/local/bin/go-doxy


# Copy configuration
COPY config.yaml /etc/go-doxy/config.yaml


# Expose proxy port
EXPOSE 80 443


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/health || exit 1


# Run go-doxy
CMD ["go-doxy", "-config", "/etc/go-doxy/config.yaml"]

Configuration File

Create a config.yaml:

listen:
  http: ":80"
  https: ":443"


docker:
  host: "unix:///var/run/docker.sock"
  watch: true


routes:
  - host: "api.example.com"
    backend: "http://api-service:8080"


  - host: "web.example.com"
    backend: "http://web-service:3000"


tls:
  enabled: false
  cert: "/etc/ssl/cert.pem"
  key: "/etc/ssl/key.pem"


logging:
  level: "info"
  format: "json"

Environment Variables Reference

VariableRequiredDescription
DOXY_CONFIGNoPath to configuration file
DOXY_HTTP_PORTNoHTTP listen port
DOXY_HTTPS_PORTNoHTTPS listen port
DOCKER_HOSTNoDocker socket path

Deploying go-doxy on Klutch.sh

    Prepare Configuration

    Create your go-doxy configuration with routing rules for your services.

    Push Your Repository to GitHub

    Commit your Dockerfile and configuration to GitHub.

    Create a New Project on Klutch.sh

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

    Create a New App

    Create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    Set up HTTP traffic:

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

    Deploy Your Application

    Click Deploy to build and launch go-doxy.

    Test Routing

    Verify routes work correctly by accessing configured hostnames.

Configuration Options

Static Routes

Define routes in configuration:

routes:
  - host: "api.example.com"
    backend: "http://localhost:8080"
    headers:
      X-Forwarded-Proto: "https"


  - host: "*.example.com"
    backend: "http://default:3000"

Docker-Based Routes

When connected to Docker, use labels:

# On containers:
labels:
  - "doxy.host=myapp.example.com"
  - "doxy.port=8080"

Path-Based Routing

Route based on URL paths:

routes:
  - host: "example.com"
    path: "/api"
    backend: "http://api:8080"


  - host: "example.com"
    path: "/"
    backend: "http://web:3000"

Load Balancing

Distribute traffic across multiple backends:

routes:
  - host: "api.example.com"
    backends:
      - "http://api-1:8080"
      - "http://api-2:8080"
      - "http://api-3:8080"
    loadbalancer: "round-robin"

Header Manipulation

Adding Headers

Add headers to proxied requests:

routes:
  - host: "example.com"
    backend: "http://backend:8080"
    headers:
      add:
        X-Request-ID: "${uuid}"
        X-Forwarded-For: "${client_ip}"

Removing Headers

Remove headers from responses:

routes:
  - host: "example.com"
    backend: "http://backend:8080"
    headers:
      remove:
        - "X-Powered-By"
        - "Server"

Health Checking

Configure health checks for backends:

routes:
  - host: "api.example.com"
    backend: "http://api:8080"
    healthcheck:
      path: "/health"
      interval: "10s"
      timeout: "5s"

WebSocket Support

go-doxy automatically handles WebSocket upgrades:

routes:
  - host: "ws.example.com"
    backend: "http://websocket-server:8080"
    websocket: true

Logging

Log Configuration

logging:
  level: "debug"  # debug, info, warn, error
  format: "json"  # json or text
  output: "stdout"

Access Logs

Enable access logging:

logging:
  access:
    enabled: true
    format: "combined"

Use Cases

Microservices Gateway

Route traffic to multiple microservices:

routes:
  - host: "api.example.com"
    path: "/users"
    backend: "http://user-service:8080"


  - host: "api.example.com"
    path: "/orders"
    backend: "http://order-service:8080"


  - host: "api.example.com"
    path: "/products"
    backend: "http://product-service:8080"

Development Environment

Mirror production routing locally during development.

Blue-Green Deployments

Switch traffic between deployment versions:

routes:
  - host: "app.example.com"
    backend: "http://app-blue:8080"
    # Switch to green by updating config

Troubleshooting

Routes Not Working

  • Verify backend is reachable
  • Check host header matching
  • Review proxy logs

Connection Timeouts

  • Increase timeout settings
  • Check backend health
  • Verify network connectivity

Docker Discovery Issues

  • Verify Docker socket access
  • Check container labels
  • Review Docker permissions

Additional Resources

Conclusion

Deploying go-doxy on Klutch.sh provides a lightweight reverse proxy solution for scenarios requiring custom routing logic or Docker container discovery. While Klutch.sh handles most routing needs automatically, go-doxy offers flexibility for more complex setups.

The combination of go-doxy’s simplicity and Klutch.sh’s reliable hosting creates a versatile platform for building custom proxy configurations.