Skip to content

feat: add bare-metal deployment support (systemd + native binaries)#67

Open
apham0001 wants to merge 1 commit into
refactofrom
feat/baremetal-deployment
Open

feat: add bare-metal deployment support (systemd + native binaries)#67
apham0001 wants to merge 1 commit into
refactofrom
feat/baremetal-deployment

Conversation

@apham0001

@apham0001 apham0001 commented Apr 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds deployment_mode: baremetal option alongside existing Docker mode. All existing Docker behavior is preserved (default).

How it works

Each role dispatches to docker.yml (existing) or baremetal.yml (new) based on deployment_mode variable.

Bare-metal support

Component Method Runtime dependency
Geth, Nethermind, Reth Native binary None
Besu Binary + script Java 21 (auto-installed)
Lighthouse, Nimbus, Prysm Native binary None
Teku Binary + script Java 21 (auto-installed)
Lodestar npm global install Node.js 22 (auto-installed)
Grandine Native binary None
Charon Native binary None
MEV-Boost Native binary None
Prometheus, Alloy Native binary None

What's included

  • 49 files (tasks, systemd templates, handlers, env templates)
  • Systemd services with proper ordering (CL After= EL)
  • System user/group (obol) with restricted permissions
  • Binary downloads from official GitHub releases
  • Prometheus scrape targets adapted for localhost
  • Alloy uses journald instead of Docker logs
  • Restart handlers on config/binary changes

Usage

# In group_vars or -e flag
deployment_mode: baremetal
ansible-playbook -i hosts.yml charon-node.yml -e deployment_mode=baremetal

Files structure

roles/<role>/
  tasks/
    main.yml      # Dispatcher
    docker.yml    # Existing Docker tasks (renamed)
    baremetal.yml # New bare-metal tasks
  templates/
    *.service.j2  # Systemd unit templates
    *.env.j2      # Environment file templates
  handlers/
    main.yml      # Restart handlers

What's left to do (before merge)

  • CI smoke test for deployment_mode: baremetal — the existing smoke-test.yml exercises the Docker path on ubuntu-latest. Bare-metal mode needs a dedicated job. Options:
    • Reuse ubuntu-latest but add a clean-up step (uninstalls systemd units between matrix runs). Risk: drift between CI and real bare-metal hosts.
    • (preferred) Run on a self-hosted runner (or ephemeral VM via actions/runner-images + actions/cache warm-up) so we get a clean Ubuntu instance per matrix entry with systemd available. Avoids polluting the GitHub-hosted runner and matches the target environment.
  • Renovate config — add datasource entries to bump binary versions (today only Docker tags are tracked; binaries are downloaded from GitHub releases per role var)
  • README — add a section explaining deployment_mode, the runtime dependency matrix, and known constraints (e.g. systemd required on the target host)
  • Validate Lodestar's npm-global install on a fresh Ubuntu without dev tooling (matrix smoke test will catch)
  • Confirm Prometheus + Alloy targets resolve correctly when EL/CL/Charon are on localhost (already templated, needs validation in CI)

Closes #38

Add `deployment_mode: baremetal` option alongside existing Docker mode.
Each role dispatches to docker.yml or baremetal.yml based on the variable.

Bare-metal support:
- EL: Geth, Nethermind, Reth, Besu (JVM)
- CL: Lighthouse, Nimbus, Prysm, Lodestar (npm), Teku (JVM), Grandine
- Charon: native binary with env file
- VC: Lighthouse, Nimbus, Prysm, Lodestar, Teku
- Tools: MEV-Boost, Prometheus, Alloy (journal-based logs)

All services managed via systemd with proper:
- System user/group (obol)
- Binary downloads from official GitHub releases
- Runtime dependencies (Node.js for Lodestar, Java 21 for Teku/Besu)
- Service ordering (CL After= EL)
- Restart handlers on config/binary changes
- Prometheus scrape targets adapted for localhost
@apham0001 apham0001 requested a review from a team as a code owner April 10, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant