Deployment Guide en

中文 | English

Deployment Guide

Maintained version: v0.51.2 ｜ Last updated: 2026-07-06

This page summarizes the three EnerOS deployment methods, OS image building, A/B partition OTA, and monitoring. For the full deployment docs see the main repo docs/deployment.md and os/*/README.md.

System Requirements

Item	Minimum	Recommended
OS	Linux Ubuntu 22.04+ / Debian 12+ or Docker	Same
Rust	1.75+ (source build only)	—
Memory	512MB	2GB+
Disk	1GB (including timeseries storage)	10GB+
Network	Open 8080 (API)	+ 16686 (Jaeger) / 9090 (Prometheus) / 3000 (Grafana)

Three Deployment Methods

1. Docker Compose (Recommended)

git clone https://github.com/Gawg-AI/EnerOS.git eneros && cd eneros
cp eneros.toml eneros.toml.local
# Edit eneros.toml.local ...

docker compose -f deploy/docker/docker-compose.yml up -d
docker compose -f deploy/docker/docker-compose.yml logs -f eneros

curl http://localhost:8080/health

Full deployment with monitoring and tracing:

docker compose -f deploy/docker/docker-compose.yml --profile monitoring --profile tracing up -d

2. Source Build

# Dev mode
./deploy/scripts/dev.sh

# Production build
./deploy/scripts/build.sh v0.51.2

# Run the release binary directly
./target/release/eneros-api run --config eneros.toml

Windows users: use cargo run --package eneros-api -- run --config eneros.toml instead of the .sh scripts.

3. OS Image (Embedded / Edge)

The os/ directory provides a complete OS image build toolchain:

Subdirectory	Purpose
os/boot/	Boot configuration (U-Boot / GRUB)
os/kernel/	Linux kernel config + patches (PREEMPT_RT / isolcpus / mlockall)
os/kernel/patches/	Kernel patches
os/rootfs/	Root filesystem (init.toml / config files / binaries)
os/image-builder/	Image build scripts (generate .img / .iso)
os/tests/	OS boot tests

See os/*/README.md in each subdirectory.

A/B Partition OTA (v0.22.0+)

EnerOS supports A/B partition OTA upgrades with Ed25519 signature verification for package integrity:

┌─────────────────────────────────────┐
│         Storage Layout              │
├─────────────────────────────────────┤
│  Bootloader │ A partition │ B partition │ User data │
│             │ (active)    │ (backup)    │           │
└─────────────────────────────────────┘

Upgrade flow:

1. Download the upgrade package to the inactive partition
2. Ed25519 signature verification
3. Write to the inactive partition
4. Switch the boot flag
5. Reboot
6. Auto-rollback to the active partition on boot failure

# Generate upgrade package
enerosctl ota pack --version 0.51.2 --output update.pkg

# Sign the upgrade package
enerosctl ota sign update.pkg /etc/eneros/keys/private.key

# Apply the upgrade
enerosctl ota apply update.pkg

Monitoring

Prometheus + Grafana

docker compose -f deploy/docker/docker-compose.yml --profile monitoring up -d
# Grafana: http://localhost:3000
# Prometheus: http://localhost:9090

EnerOS exposes metrics at: GET /api/v1/metrics (Prometheus format)

Jaeger Distributed Tracing

docker compose -f deploy/docker/docker-compose.yml --profile tracing up -d
# Jaeger UI: http://localhost:16686

EnerOS sends traces to Jaeger via OpenTelemetry.

Logging

[observability]
log_level = "info"
enable_tracing = true
jaeger_endpoint = "http://localhost:4317"

Dynamic log level adjustment (no restart needed):

curl -X POST http://localhost:8080/api/config/reload

Multi-Tenant Deployment

See the Multi-Tenancy page and docs/deployment.md §3.3.

Zero-Trust Deployment

See the Zero-Trust Security page and docs/deployment.md §3.4.

Operations Automation Deployment

See the Operations & Plugins page and docs/deployment.md §3.5.

High Availability Deployment

See the HA & Multi-Region page and docs/deployment.md §3.6.

Known Limitations (v0.51.2)

• Windows / macOS support core library development only, not production deployment
• OS image building supports Linux x86_64 / aarch64 only
• OTA supports A/B partition only, no delta upgrades
• Monitoring dashboards require manual Grafana JSON import

Related Documentation

• Main repo docs/deployment.md — Full deployment docs
• Main repo os/boot/README.md — Boot configuration
• Main repo os/kernel/README.md — Kernel configuration
• Main repo os/rootfs/README.md — Root filesystem
• Main repo os/image-builder/README.md — Image building
• Main repo deploy/docker/docker-compose.yml — Docker Compose config
• Wiki Installation — Installation method quick reference
• Wiki Configuration Reference — eneros.toml section quick reference