Building from Source

Relevant source files

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

• Cargo.toml
• rust-toolchain.toml
• README.md
• AGENTS.md
• src/main.rs

Building Hodor from source allows you to create a platform-specific binary of this tiny Rust reverse proxy. The process produces a single, self-contained executable that gates web applications behind a shared password.

Sources: README.md:3-5, AGENTS.md:7-9

Prerequisites

You must install the Rust toolchain to compile the project. Hodor specifies its environment requirements in the toolchain configuration file.

• Rust Version: 1.85 or higher.
• Toolchain Channel: Stable.
• Components: rustfmt and clippy.

Sources: Cargo.toml:10, rust-toolchain.toml:1-4

Build Process

The build process uses Cargo, the Rust package manager, to resolve dependencies and compile the source code.

Development and Release Builds

You can perform a standard build or an optimized release build:

1. Debug Build: Run cargo build to create a binary for local development.
2. Release Build: Run cargo build --release to create an optimized binary for production use.

The resulting binary is located at ./target/release/hodor.

Sources: AGENTS.md:61-63, README.md:188-192

Dependency Management

Hodor relies on several core Rust libraries for its functionality. Cargo manages these automatically during the build process.

Category	Key Libraries
Asynchronous Runtime	tokio
Web Framework	axum, hyper, hyper-util
Templating	minijinja
Configuration	figment, serde
Security/Crypto	hmac, sha2, subtle

Sources: Cargo.toml:13-31, AGENTS.md:50-56

Testing and Quality Assurance

Before deploying, verify the build integrity using the built-in test suite and linting tools.

Running Tests

Hodor includes a suite of unit and integration tests. Run them using:

cargo test

Sources: README.md:195-197, AGENTS.md:64

Code Quality and Formatting

The project enforces strict code quality rules. Maintainers use the following commands to ensure the codebase remains clean:

• Linting: cargo clippy -- -D warnings ensures no compiler warnings exist.
• Formatting: cargo fmt -- --check verifies that code adheres to the standard style.

Sources: AGENTS.md:64-65, AGENTS.md:88-91

Coverage Reports

You can generate detailed HTML coverage reports using cargo-llvm-cov. This requires the tool to be installed separately.

cargo install cargo-llvm-cov --locked
cargo llvm-cov --all-features --workspace --open

Sources: README.md:199-204

Build Workflow

The following diagram illustrates the lifecycle of a source build, from environment setup to a validated binary.

The flow shows the sequence of commands required to move from source code to a production-ready binary.

Sources: AGENTS.md:61-65, README.md:188-197, rust-toolchain.toml:1-4

Containerization

Hodor is designed to run from a scratch image, resulting in a very small container (~5MB).

Local Docker Build

To build the Docker image locally:

docker build -t hodor .

CI/CD Pipeline

The project uses GitHub Actions for automated builds and releases.

• CI: Runs tests, formatting, and linting on every push or pull request.
• Release: Triggered by version tags (e.g., v1.0.0), it builds multi-arch Docker images and pushes them to ghcr.io.

Sources: README.md:21-22, README.md:209-211, AGENTS.md:73-77

Building Hodor from source ensures you have the latest features and security updates directly from the codebase. By following the standard Rust build pipeline, you produce a high-performance, minimal reverse proxy suitable for Docker sidecar deployments.

Sources: AGENTS.md:7-9, README.md:3-17