Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (82 loc) · 3.88 KB

CONTRIBUTING.md

File metadata and controls

109 lines (82 loc) · 3.88 KB
Raw

Contributing to Hestia

Thanks for wanting to help keep the home fire burning! 🔥 Hestia is in early development, so contributions of every size are welcome — code, docs, bug reports, and ideas.

Dev setup

You'll need a Mac with Apple Silicon and:

Tool Install
Rust (stable) https://rustup.rs
Node.js 20+ brew install node
Apple container CLI https://github.com/apple/container/releases

First-time runtime setup:

container system start
container system kernel set --recommended

Running the stack locally

Three processes, three terminals (or background the first two):

# 1. Agent — talks to the local container runtime
HESTIA_AGENT_ADDR=127.0.0.1:4400 cargo run -p hestia-agent

# 2. Server — aggregates agents, serves the API
HESTIA_SERVER_ADDR=127.0.0.1:4300 \
HESTIA_AGENTS="mini-local=http://127.0.0.1:4400" \
cargo run -p hestia-server

# 3. UI — Vite dev server with hot reload, proxies /v1 to the server
npm --prefix hestia-ui install
npm --prefix hestia-ui run dev     # → http://localhost:5173

Set RUST_LOG=hestia_agent=debug (or hestia_server=debug) for verbose logs.

This setup runs with auth disabled (no HESTIA_ADMIN_PASSWORD / HESTIA_AGENT_TOKEN set) for a frictionless dev loop — both processes log a warning about it at startup. To test the login flow locally, add HESTIA_ADMIN_PASSWORD=dev to the server's env and HESTIA_AGENT_TOKEN=dev to both. See hestia-server/README.md.

Project layout

Path What it is
hestia-agent/ Rust. Runs on each Mac Mini; wraps the container CLI, exposes REST + WebSocket.
hestia-server/ Rust. Central API: aggregation, action proxying, serves the UI bundle.
hestia-ui/ React + TypeScript. Proxmox-style web UI.
scripts/ Bootstrap installers for real deployments.
assets/ Brand assets (logomark, favicon, lockups).

Each component has its own README with endpoint tables and TODOs.

Before opening a PR

cargo fmt --all
cargo clippy --workspace
cargo test --workspace
npm --prefix hestia-ui run lint
npm --prefix hestia-ui run typecheck
npm --prefix hestia-ui run build

Unit tests cover pure logic only — JSON parsing (hestia-agent/src/container.rs), auth internals (hestia-server/src/auth.rs), and agent-spec parsing (hestia-server/src/agents.rs). Anything that shells out to container or talks over the network is exercised manually against the real runtime, not mocked.

CI (.github/workflows/ci.yml) runs all of the above on every PR, plus a cargo llvm-cov line-coverage gate. The gate starts at 30% (current baseline ~34%) and should be raised as more pure-logic tests land — it stays deliberately low so nobody's tempted to mock the runtime just to hit a number.

The project's bar for merging: changes are verified against the real runtime, not just compiled. If you touch the agent or server, exercise the affected endpoints against a live container runtime and say so in the PR. For UI changes, include a screenshot.

Conventions

  • Branches: feat/short-description, fix/short-description.
  • Commits: imperative, sentence-style summaries (Add image pull endpoint to hestia-agent), matching the existing history.
  • Code style: rustfmt / project defaults; match the surrounding code. The agent parses container CLI JSON with typed serde structs — if you add a new CLI interaction, inspect the real output first and type it.
  • Scope: small, focused PRs merge fast. Big ideas → open an issue first so we can align before you invest time.

Reporting bugs

Use the bug template — the environment section (macOS version, container --version, commit hash) and RUST_LOG=debug output make most bugs solvable without back-and-forth.

License

By contributing, you agree that your contributions are licensed under the MIT License.