DOCSEARCHbyAlgolia
Submit Docs

GoDoxy

repository·main·Indexed 23 days ago

https://github.com/yusing/godoxy

A lightweight and performant reverse proxy with a WebUI. It features automatic routing for Docker/Podman containers, Proxmox integration (LXC/Node management), and advanced traffic management including OpenID Connect and idle sleep. The system includes a secure GoDoxy Agent for mTLS-protected Docker socket proxying, system monitoring, and TCP/UDP stream tunneling via TLS/DTLS.

Tokens
63.5K
Snippets
200
Records
373
Agent score
85%

What's inside godoxy

  1. Overview of GoDoxy v1 REST API

    main
    The internal/api/v1 package provides the HTTP handlers for GoDoxy's REST API using the Gin web framework. It exposes endpoints for managing routes, Docker containers, certificates, system metrics, and configuration. The API is primarily consumed by the GoDoxy WebUI.

  2. Overview of the GoDoxy Agent

    main

    The GoDoxy Agent is a secure monitoring and proxy agent designed to run alongside Docker containers. It operates as a TLS-enabled server providing the following core capabilities:

    • Secure Docker socket proxying: Uses client certificate authentication (mTLS) to protect the Docker socket.
    • HTTP proxying: Provides proxy capabilities for container traffic.
    • System monitoring: Collects and monitors system metrics.
    • Health checks: Provides endpoints to verify agent status.

  3. Overview of GoDoxy

    main
    GoDoxy is a lightweight reverse proxy designed for Docker containers, featuring an integrated WebUI for management. The system coordinates configuration loading, an API server, authentication, and monitoring services to manage proxy traffic and container routing.

  4. Overview of the agent/pkg/agent/stream package

    main

    The agent/pkg/agent/stream package implements a header-based handshake protocol that allows authenticated clients to request forwarding to a specific (host, port) destination. It supports two transport modes:

    1. TCP-over-TLS: For TCP stream tunneling.
    2. UDP-over-DTLS: For UDP datagram forwarding.

    The protocol uses a fixed-size 275-byte binary header to negotiate the tunnel. It is designed to work alongside HTTPS API traffic by using the godoxy-agent-stream/1 ALPN protocol for multiplexing.

  5. Overview of GoDoxy logging subsystems

    main

    GoDoxy uses a structured logging system composed of three main subsystems:

    • Application Logger: A Zerolog-based console logger that uses level-aware formatting.
    • Access Logger: Handles HTTP request/response logging with support for configurable formats, filters, and destinations (e.g., File, Stdout).
    • In-Memory Logger: A circular buffer system that supports real-time log viewing via WebSocket streaming.

    Note that this system is not intended for log aggregation across multiple instances or for sending structured logs to external systems like Datadog.

  6. Overview of Docker Socket Proxy

    main

    The Docker Socket Proxy is a secure gatekeeper that exposes the Docker socket with fine-grained access control. It intercepts HTTP requests and allows or denies access to Docker API endpoints based on configured permissions.

    Key advantages include:

    • No EOF errors: Properly handles keep-alive connections to avoid EOF errors common in other implementations.
    • GoDoxy integration: Designed for seamless container auto-discovery and route management within the GoDoxy ecosystem.

  7. Use the internal/route/rules engine for HTTP processing

    main

    The internal/route/rules package implements a rule engine for conditional HTTP request and response processing. It allows you to match requests based on headers, paths, methods, IPs, and more, then execute actions like header manipulation, authentication, routing, or terminating the request with an error or redirect.

    Rules operate in two main phases:

    1. Pre phase: Evaluates request-based matchers and executes commands. If a terminating action (like proxy or error) is triggered, the pre-phase stops.
    2. Post phase: Executes after the upstream response is received. It evaluates response-based matchers (like status or resp_header) and runs associated commands.

  8. Use the reverseproxy package for Unix socket proxying

    main

    The reverseproxy package provides an HTTP reverse proxy implementation specifically designed for proxying requests to Unix sockets (such as the Docker socket). It is a simplified version of Go's net/http/httputil.ReverseProxy optimized for socket proxying use cases.

    Key Characteristics

    • Director-only: Only the Director function is supported for request modification. The Rewrite and ModifyResponse hooks from the standard library are not available.
    • Context-aware streaming: Uses ioutils.CopyCloseWithContext to respect request cancellation, use Content-Length for optimal copying, and handle trailer headers.
    • No buffering: Streams responses directly to the client without the buffering behavior found in the standard library.
    // Example of initializing a ReverseProxy for a Unix socket
rp := &reverseproxy.ReverseProxy{
    Director: func(req *http.Request) {
        req.URL.Scheme = "http"
        req.URL.Host = "api.moby.localhost"
        req.RequestURI = req.URL.String()
    },
    Transport: &http.Transport{
        DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
            return net.DialTimeout("unix", "/var/run/docker.sock", 5*time.Second)
        },
        DisableCompression: true,
    },
}

http.HandleFunc("/", rp.ServeHTTP)
http.ListenAndServe(":2375", nil)

  9. Monitor system metrics and route uptime

    main

    The internal/metrics package provides system monitoring and metrics collection with time-series storage. It is composed of several specialized packages:

    • systeminfo/: Collects system metrics including CPU, memory, disk, network, and sensors.
    • uptime/: Monitors route health status.
    • period/: The core framework providing time-bucketed metrics storage, including Period[T] containers, Poller[T, A] background collectors, and Entries[T] circular buffers for time-series data.

  11. Manage container lifecycle with idlewatcher

    main

    The internal/idlewatcher package manages container lifecycles based on idle timeouts. It can automatically stop, pause, or kill containers when they are idle for a configured duration and automatically wake them when a new request arrives.

    Key features include:

    • Automatic Wake-up: Containers are started/resumed upon request.
    • Loading Pages: Serves HTML loading pages to users while a container is waking up.
    • SSE Events: Provides real-time wake-up progress via Server-Sent Events (SSE).
    • Dependency Management: Supports waking up containers in a specific order based on dependencies.

  12. Understand the Route lifecycle and responsibilities

    main

    The internal/route package manages the Route object, which acts as the central configuration and metadata container for routes loaded from various sources (YAML, Docker labels, agents, etc.).

    Key Responsibilities:

    • Defining route configuration fields and JSON/OpenAPI shapes.
    • Tracking metadata (Provider, Docker/Proxmox, health, runtime).
    • Managing lifecycle via ValidateContext, Start, and Finish.
    • Providing helpers like ShouldExclude, UseHealthCheck, Key, and References.

    Note: This package does not handle concrete request handling (reverse proxy, file serving, etc.). Implementation construction is delegated to a builder registered via InitBuilder.