Edge Deployment (Operator Guide)

This guide describes running edged with systemd using the implemented precheck gate and state-root reconstruction flow.

Deployment Model

Units in deploy/systemd/ define this order:

  1. edged-precheck.service (oneshot)

  2. edged.service (daemon; requires precheck success)

edged.service declares:

  • After=... edged-precheck.service

  • Requires=edged-precheck.service

  • Wants=edged-precheck.service

If precheck exits non-zero, daemon startup is blocked.

Required Inputs

Minimum required operator inputs:

  • config file for --config (template points to ${STATE_ROOT}/bootstrap/config.yaml)

  • transport cert/key/CA files from config

  • writable state root (EDGE_STATE_ROOT)

Reconstruction path also requires:

  • ${STATE_ROOT}/runtime/manifest.json

  • ${STATE_ROOT}/runtime/manifest.json.sig

  • ${STATE_ROOT}/identity/manifest-verify.pub

Canonical State Root Layout

{root}/edge/segments/
{root}/edge/relay/
{root}/identity/
{root}/runtime/
{root}/runtime/binaries/
{root}/epoch/
{root}/bootstrap/

Precheck Exit Codes

edged precheck --config ... returns:

  • 0: clean (first run initialized, fingerprint match, or reconstruction success)

  • 1: config parse/validation failure

  • 2: state-root validation failure

  • 3: certificate/CA unreadable or cert expires within 7 days

  • 5: reconstruction path failure

Systemd Setup

Example setup with template files:

# 1) Install binaries and unit templates.
sudo install -m 0755 ./edge/edged /usr/local/bin/edged
sudo install -m 0644 deploy/systemd/edged-precheck.service.template /etc/systemd/system/edged-precheck.service
sudo install -m 0644 deploy/systemd/edged.service.template /etc/systemd/system/edged.service

# 2) Edit unit files for your install prefix + state root placeholders.
#    (@INSTALL_PREFIX@, @STATE_ROOT@)

# 3) Reload units and enable precheck/daemon.
sudo systemctl daemon-reload
sudo systemctl enable edged-precheck.service edged.service
sudo systemctl start edged.service

Manual Precheck and Validation

# Structural + startup validation summary.
GOWORK=off go run ./edge/cmd/edged validate --config ./edge/config/testdata/valid_full.yaml

# Precheck gate and exit code.
GOWORK=off go run ./edge/cmd/edged precheck --config ./edge/config/testdata/valid_full.yaml
echo $?

Verify Runtime Health

# Control socket (default path).
./edge/edgectl --socket /run/edged/ctl.sock status
./edge/edgectl --socket /run/edged/ctl.sock storage stats
./edge/edgectl --socket /run/edged/ctl.sock retry list

# Logs.
journalctl -u edged-precheck -n 200 --no-pager
journalctl -u edged -n 200 --no-pager

Expected precheck lifecycle logs on update path:

  • edge.os.update_detected

  • edge.os.reconstruction_started

  • edge.os.reconstruction_completed

Compatibility Notes

  • edged binary and edge/ module are canonical.

  • Legacy swarm* compatibility surfaces are removed in current master.

  • Environment overrides are EDGE_* only.

Evidence

Code:

  • edge/cmd/edged/main.go (precheckCmd, runPrecheck, runDaemon)

  • edge/stateroot/stateroot.go

  • edge/bootstrap/bootstrap.go

  • edge/bootstrap/install.go

  • edge/epoch/epoch.go

Systemd templates:

  • deploy/systemd/edged-precheck.service.template

  • deploy/systemd/edged.service.template

Tests:

  • edge/cmd/edged/precheck_test.go

  • edge/bootstrap/bootstrap_test.go

  • edge/bootstrap/install_test.go

  • edge/epoch/epoch_test.go

Captured outputs:

  • docs/_generated/test-outputs/edged-help.txt

  • docs/_generated/test-outputs/edgectl-help.txt

  • docs/_generated/test-outputs/edged-integration.txt