Docker Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• src/config.rs
• src/main.rs
• src/state.rs
• src/proxy.rs

Hodor deploys as a lightweight Docker sidecar to protect web applications behind a single shared password. The container runs from a minimal scratch image, resulting in a binary size of approximately 5MB. It functions by intercepting incoming traffic and either serving a login page or streaming requests to the configured upstream application.

Sources: README.md:3-8, AGENTS.md:5-7, README.md:27.

Architecture and Flow

Hodor follows the sidecar pattern where the proxy container and the application container reside within the same network namespace or logical grouping (such as a Docker Compose project or Kubernetes Pod).

Request Interception

Hodor handles all incoming requests through a fallback mechanism defined in the Axum router. It identifies the client IP by inspecting the TCP peer address or X-Forwarded-For headers if TRUST_PROXY is enabled.

1. Public Access: Requests matching BYPASS_PATHS skip authentication.
2. Network Bypass: Requests from IPs within BYPASS_CIDRS skip authentication.
3. Session Validation: Hodor checks for a valid HMAC-SHA256 signed session cookie.
4. Upstream Proxy: If authorized, Hodor adds the X-Hodor-Auth header and streams the request to the UPSTREAM URL.

Sources: src/main.rs:24-29, src/proxy.rs:60-75, AGENTS.md:12-16

Configuration via Environment Variables

Docker deployments rely on environment variables to override default settings and the hodor.toml file.

Environment Variable	Required	Default	Description
PASSWORD	Yes	-	The shared password for the login page.
UPSTREAM	Yes	-	The internal URL of the app (e.g., http://app:80).
SECRET	No	random	Key used to sign session cookies.
LISTEN	No	:8080	Port and address the proxy listens on.
TRUST_PROXY	No	false	Enables parsing of X-Forwarded-For from upstream proxies.

Sources: README.md:46-68, src/config.rs:134-177

Volume Mounts for Customization

You can inject custom templates or styles by mounting volumes into the container. Hodor reads these paths at startup to populate the AppState.

services:
  gate:
    image: ghcr.io/michidk/hodor:latest
    environment:
      TEMPLATE: /etc/hodor/login.html
      CUSTOM_CSS: "body { background: #000; }"
    volumes:
      - ./my-login.html:/etc/hodor/login.html:ro

Sources: README.md:180-185, src/state.rs:70-75

Container Lifecycle and Health

Hodor provides mechanisms for orchestrators to monitor and manage the container lifecycle.

Health Probes

The endpoint /_gate/health returns a 200 OK status to indicate the Hodor process is active. This endpoint bypasses all authentication checks. It does not verify the health of the upstream service.

Sources: README.md:214-220, src/main.rs:27

Graceful Shutdown

The application listens for SIGTERM signals, which are standard for Docker and Kubernetes shutdowns. Upon receiving the signal, the server stops accepting new connections and completes active requests before exiting.

Network Security in Docker

To ensure the security of the deployment, the upstream application must only be reachable via the Hodor proxy.

• Restricted Access: Bind the upstream application to a private bridge network or loopback interface.
• Header Integrity: Hodor strips any client-supplied X-Hodor-* headers to prevent authentication spoofing.
• IP Resolution: When Hodor runs behind an ingress (like Traefik or Nginx), TRUST_PROXY=true and TRUSTED_PROXY_CIDRS must be configured to correctly resolve the client's origin IP for rate limiting and bypasses.

Sources: src/proxy.rs:157-167, README.md:111-122, AGENTS.md:21-24