Edgelet installation and upgrade

Install Edgelet on linux, darwin, and windows using install.sh. Releases ship raw binaries only (no .tar.gz install bundles, no DEB/RPM).

For production topology (systemd layout, engine selection, provisioning workflow), see Deployment.

Version pin

Platform train v3.8.0 requires Edgelet v1.0.0. Use this tag for fresh installs and fleet upgrades unless your Controller specifies a newer patch on the same train.

Overview

Platform	Install artifact	Default containerEngine	OTA via install.sh
linux	Thin wrapper + zstd-embedded fat runtime	edgelet	Yes (native + controller-driven)
darwin	Monolithic binary	docker	Manual binary replace only
windows	Monolithic .exe	docker	Not supported by version handler

Fleet upgrades on linux use two layers:

Layer	Mechanism	On-disk state
1 - Thin binary	install.sh --upgrade / --rollback	/var/backups/edgelet/ receipts and cache
2 - Fat embed	edgelet daemon extract on new embed hash	/var/lib/edgelet/data/current, data/previous

See Architecture for the thin/fat model.

Forbidden upgrade paths: iofog-agentvc.jar, apt/dnf/yum edgelet packages, or any path that bypasses install.sh on linux native installs.

Prerequisites

Platform	Requirements
linux	Root/sudo; Ubuntu 20.04+, RHEL 8+, Debian 11+ (or equivalent); network for online install
darwin	Admin for /usr/local/bin; Docker or Podman when not using linux embedded engine
windows	Admin; Docker or Podman
containerEngine: edgelet (linux)	No external container runtime on the host
docker / podman	Docker 26.10+ or Podman 3.0+

Linux init detection (auto): systemd, procd (OpenWrt), OpenRC, SysV, upstart, s6, runit.

Release artifacts

Per tag on GitHub Datasance/edgelet (override with EDGELET_GITHUB_REPO):

OS / arch	Binary file
linux amd64 / arm64 / arm / riscv64	edgelet-linux-<arch>
darwin amd64 / arm64	edgelet-darwin-<arch>
windows amd64	edgelet-windows-amd64.exe

Also published: SHA256SUMS, edgelet-config.yaml.sample, edgelet-controller-ca.crt.sample, install.sh, uninstall.sh.

Download URL pattern:

https://github.com/Datasance/edgelet/releases/download/<tag>/edgelet-<os>-<arch>[.exe]

Build locally: make release-binaries VERSION={EDGELET_VERSION} → dist/.

The fat runtime inside the linux zstd embed is statically linked by default, so one artifact runs on glibc and musl (Alpine, OpenWrt).

Install paths

Purpose	Linux	macOS	Windows
Binary	/usr/local/bin/edgelet	/usr/local/bin/edgelet	%ProgramFiles%\Edgelet\edgelet.exe
Config	/etc/edgelet/config.yaml	/etc/edgelet/config.yaml	%ProgramData%\Edgelet\config\config.yaml
Controller CA	/etc/edgelet/cert.crt	same	same
Data	/var/lib/edgelet/	/var/lib/edgelet/	%ProgramData%\Edgelet\data\
Runtime	/run/edgelet/	/var/run/edgelet/	%ProgramData%\Edgelet\run\
Logs	/var/log/edgelet/	/var/log/edgelet/	%ProgramData%\Edgelet\log\
Scripts	/usr/share/edgelet/	/usr/local/share/edgelet/	%ProgramData%\Edgelet\scripts\
OTA metadata	/var/backups/edgelet/	-	-

Linux thin runtime chain: /usr/local/bin/edgelet → lazy extract → /var/lib/edgelet/data/current/bin/edgelet (fat).

Fresh installation

Online

curl -fsSL https://github.com/Datasance/edgelet/releases/download/v1.0.0/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh --version=v1.0.0

When --version is omitted or set to latest, the script resolves the tag from GitHub releases/latest before downloading the binary.

From a clone (dev / CI)

sudo ./install.sh --bin-path=build/edgelet-linux-amd64 --version=dev

Airgap

On a connected machine, download the binary and verify against SHA256SUMS, then copy to the edge host:

sudo ./install.sh \
  --airgap \
  --bin-path=/tmp/edgelet-linux-arm64 \
  --expected-sha256=<sha256-from-SHA256SUMS> \
  --version=v1.0.0

Alternatively use --checksum-path=SHA256SUMS with the manifest in the same directory as the binary.

First-time configuration

If /etc/edgelet/config.yaml is missing, install.sh installs a sample from packaging or /usr/share/edgelet/edgelet-config.yaml.sample. You can also run:

sudo edgelet init-config

init-config is idempotent and does not overwrite an existing file. See Configuration.

Controller CA (/etc/edgelet/cert.crt) is not installed by default. For lab installs use --with-sample-ca; for production use edgelet provision or edgelet config cert.

Install flags

Flag	Purpose
--version=	Release tag (default latest when downloading)
--arch=	Override auto-detected arch (amd64, arm64, arm, riscv64)
--bin-path=	Local binary (dev, airgap, CI)
--airgap	Offline; requires --bin-path
--expected-sha256=	Verify local binary SHA256
--checksum-path=	SHA256SUMS file for verification
--upgrade / --rollback	In-place thin-binary OTA
--force-config	Replace config from sample (destructive)
--with-sample-ca	Copy sample controller CA if cert.crt missing
--container-engine=	edgelet, docker, or podman (linux default: edgelet)

Environment: EDGELET_VERSION, EDGELET_GITHUB_REPO.

After install

install.sh does not provision the Edgelet node. On linux it installs the init unit and starts edgelet.service (and edgelet-containerd when containerEngine=edgelet). On darwin and windows it starts edgelet daemon in the background; logs go to edgelet.0.log under the platform log directory.

edgelet --version
edgelet system status
edgelet config --a <controller-api-endpoint>
edgelet provision <provisioning-key>

Orchestrators (potctl) must not pass provision keys to install.sh. See Deployment.

Upgrade and rollback

Use the bundled script path so controller OTA and manual paths stay aligned:

# Upgrade to a specific release
sudo sh /usr/share/edgelet/install.sh --upgrade --version=v1.0.0

# Upgrade to GitHub latest
sudo sh /usr/share/edgelet/install.sh --upgrade

# Rollback to previous-release
sudo sh /usr/share/edgelet/install.sh --rollback

On upgrade, install.sh backs up config, caches the old binary, writes previous-release metadata, stops the daemon, replaces the binary, and restarts via init.

OTA readiness

Edgelet does not self-upgrade when readiness is true. Readiness flags tell the Controller that the Edgelet node can accept a version command. The field agent publishes isReadyToUpgrade and isReadyToRollback on the status heartbeat.

Key gates for readyToUpgrade:

• Not mid-OTA (60s window after version change)
• Not EDGELET_DAEMON=container
• Not Windows
• /usr/share/edgelet/install.sh exists
• Daemon healthy
• Installed version differs from target

Verify locally:

grep installed_version /var/backups/edgelet/install-receipt
edgelet --version
test -f /usr/share/edgelet/install.sh && echo ok

Controller-driven upgrade

When the Controller sets changes.version=true, the field agent fetches the version command and may launch install.sh in the background.

Flat v3.8 shape:

{
  "versionCommand": "upgrade",
  "provisionKey": "<one-time-key>",
  "expirationTime": 1718380800000,
  "semver": "1.0.0"
}

Controller-driven OTA rotates the agent ed25519 key without changing iofogUuid. Manual install.sh runs do not auto-reprovision.

Container deployments (EDGELET_DAEMON=container)

When Edgelet runs inside a release container image with EDGELET_DAEMON=container:

Item	Value
Image	ghcr.io/datasance/edgelet:1.0.0
OTA	Orchestrator replaces image tag (not install.sh)

See Deployment.

Uninstall

sudo sh uninstall.sh
sudo sh uninstall.sh --remove-data   # also removes /etc/edgelet when set

Bundled copy (linux): sudo sh /usr/share/edgelet/uninstall.sh.

Troubleshooting

Symptom	Check
readyToUpgrade never true	Receipt version vs target; daemon health; missing /usr/share/edgelet/install.sh
Controller OTA no-op	Readiness false at command time; inspect daemon logs for version handler
Rollback fails	previous-release missing; cache deleted; URL unreachable
MS down after upgrade	New embed hash → control-plane and data-plane restart

See also

Document	Topic
Deployment	Production topology, engines, potctl contract
Architecture	Thin/fat model, OTA layers
Configuration	Config file and profiles

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!