Chapter 1

Installation

This guide covers all methods to install and run energy2mqtt, from the simplest Docker deployment to compiling from source.

Quick Start

The fastest way to get started is using Docker:

# Pull and run the container
docker run -d \
  --name energy2mqtt \
  -v ./config:/config \
  -p 8080:8080 \
  ghcr.io/energy2mqtt/energy2mqtt:latest

Then create your configuration file at ./config/e2m.yaml and restart the container.

Installation Methods

Choose the method that best fits your needs:

Method	Best For	Difficulty
Docker	Most users, easy updates	Easy
Podman	Rootless containers	Easy
Binary Download	Direct installation	Medium
Compile from Source	Developers, customization	Advanced

Docker Installation

Docker is the recommended way to run energy2mqtt. It includes all dependencies and is easy to update.

Prerequisites

Docker installed (Install Docker)
Docker Compose (optional, included with Docker Desktop)

Using Docker Run

# Create config directory
mkdir -p ~/energy2mqtt/config

# Run the container
docker run -d \
  --name energy2mqtt \
  --restart unless-stopped \
  -v ~/energy2mqtt/config:/config \
  -p 8080:8080 \
  ghcr.io/energy2mqtt/energy2mqtt:latest

Using Docker Compose

Create a docker-compose.yaml file:

services:
  energy2mqtt:
    image: ghcr.io/energy2mqtt/energy2mqtt:latest
    container_name: energy2mqtt
    restart: unless-stopped
    volumes:
      - ./config:/config
    ports:
      - "8080:8080"
    # Optional: connect to your MQTT broker network
    # networks:
    #   - mqtt_network

Then run:

docker compose up -d

Docker Volume Mounts

Mount Point	Purpose
`/config`	Configuration files (e2m.yaml)
`/defs`	Custom device definitions (optional)

Details

The container runs as a minimal “scratch” image with only the necessary files. This makes it lightweight and secure.

Podman Installation

Podman is a rootless alternative to Docker. The commands are nearly identical.

# Create config directory
mkdir -p ~/energy2mqtt/config

# Run with Podman
podman run -d \
  --name energy2mqtt \
  --restart unless-stopped \
  -v ~/energy2mqtt/config:/config:Z \
  -p 8080:8080 \
  ghcr.io/energy2mqtt/energy2mqtt:latest

Details

The :Z suffix on the volume mount is important for SELinux-enabled systems (Fedora, RHEL, CentOS).

Podman Quadlet (Systemd Integration)

For systemd integration, create /etc/containers/systemd/energy2mqtt.container:

[Container]
Image=ghcr.io/energy2mqtt/energy2mqtt:latest
ContainerName=energy2mqtt
Volume=/home/user/energy2mqtt/config:/config:Z
PublishPort=8080:8080

[Service]
Restart=always

[Install]
WantedBy=default.target

Then enable and start:

systemctl --user daemon-reload
systemctl --user enable --now energy2mqtt

Binary Installation

If you prefer running energy2mqtt directly without containers, you can download the pre-built binary.

Prerequisites

Linux x86_64 (other architectures: compile from source)
GLIBC 2.31+ (Debian 11+, Ubuntu 20.04+, Fedora 32+)

Download and Install

# Create installation directory
sudo mkdir -p /opt/energy2mqtt
cd /opt/energy2mqtt

# Download latest binary
sudo wget https://energy2mqtt.org/download/stable/energy2mqtt
sudo chmod +x energy2mqtt

# Create config directory
sudo mkdir -p /etc/energy2mqtt

# Download device definitions
sudo wget -O defs.tar.gz https://energy2mqtt.org/download/stable/defs.tar.gz
sudo tar -xzf defs.tar.gz

Details

TODO: Verify download URLs and add checksums for binary verification.

Create Systemd Service

Create /etc/systemd/system/energy2mqtt.service:

[Unit]
Description=energy2mqtt - Energy Data to MQTT Bridge
After=network.target mosquitto.service

[Service]
Type=simple
User=energy2mqtt
Group=energy2mqtt
WorkingDirectory=/opt/energy2mqtt
ExecStart=/opt/energy2mqtt/energy2mqtt --config /etc/energy2mqtt/e2m.yaml
Restart=on-failure
RestartSec=10

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/etc/energy2mqtt

[Install]
WantedBy=multi-user.target

Enable and start the service:

# Create service user
sudo useradd -r -s /bin/false energy2mqtt

# Set permissions
sudo chown -R energy2mqtt:energy2mqtt /opt/energy2mqtt
sudo chown -R energy2mqtt:energy2mqtt /etc/energy2mqtt

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable energy2mqtt
sudo systemctl start energy2mqtt

# Check status
sudo systemctl status energy2mqtt

Compiling from Source

For developers or when you need a custom build (different architecture, modifications).

Prerequisites

Install the Rust toolchain:

# Install Rust using rustup (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts, then reload your shell
source ~/.cargo/env

# Verify installation
rustc --version
cargo --version

Minimum Rust version: 1.70+ (2021 edition)

Build Dependencies

On Debian/Ubuntu:

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev

On Fedora/RHEL:

sudo dnf install -y gcc openssl-devel

On Arch Linux:

sudo pacman -S base-devel openssl

Clone and Build

# Clone the repository
git clone https://github.com/energy2mqtt/energy2mqtt.git
cd energy2mqtt

# Build in release mode (optimized)
cargo build --release

# The binary is at: target/release/energy2mqtt

Build Options

Command	Description
`cargo build`	Debug build (faster compile, slower runtime)
`cargo build --release`	Release build (slower compile, optimized)
`cargo test`	Run all tests
`cargo doc --open`	Generate and open documentation

Release Build Optimizations

The release build is optimized for size with these settings in Cargo.toml:

[profile.release]
lto = true           # Link-time optimization
codegen-units = 1    # Single codegen unit for better optimization
panic = "abort"      # Smaller binary, no unwinding
strip = true         # Strip debug symbols
opt-level = "z"      # Optimize for size

Cross-Compilation

To build for a different architecture (e.g., ARM for Raspberry Pi):

# Add target
rustup target add aarch64-unknown-linux-gnu

# Install cross-compiler (Debian/Ubuntu)
sudo apt install gcc-aarch64-linux-gnu

# Build for ARM64
cargo build --release --target aarch64-unknown-linux-gnu

Details

For easier cross-compilation, consider using cross:

cargo install cross
cross build --release --target aarch64-unknown-linux-gnu

Building the Docker Image

# Build the Docker image locally
docker build -t energy2mqtt:local .

# Run your local build
docker run -d \
  --name energy2mqtt \
  -v ./config:/config \
  -p 8080:8080 \
  energy2mqtt:local

Configuration

After installation, create your configuration file.

Minimal Configuration

Create e2m.yaml (in /config for Docker, or /etc/energy2mqtt for binary):

mqtt:
  host: localhost
  port: 1883
  user: energy2mqtt
  pass: your_password
  ha_enabled: true

Full Configuration Example

# MQTT broker connection (required)
mqtt:
  host: localhost
  port: 1883
  user: energy2mqtt
  pass: your_password
  ha_enabled: true          # Enable Home Assistant auto-discovery

# ZENNER Datahub connection (optional)
zenner_datahub:
  - name: "my_datahub"
    enabled: true
    broker_host: mqtt.datahub.zenner.com
    broker_port: 1883
    broker_user: your_user
    broker_pass: your_pass
    base_topic: "your_tenant"
    client_name: "energy2mqtt"
    update_interval: 60

# Modbus devices (optional)
modbus:
  hubs:
    - name: "main_hub"
      host: "192.168.1.100"
      port: 502
      proto: TCP
      devices:
        - name: "Electricity Meter"
          meter: "dzg"
          slave_id: 1
          read_interval: 30

# OMS meters (optional)
oms:
  - name: "Water Meter"
    id: "07ELS3312345678"
    key: "0102030405060708090A0B0C0D0E0F10"

Configuration File Locations

Installation Method	Config Location
Docker/Podman	`/config/e2m.yaml` (mounted volume)
Binary	`/etc/energy2mqtt/e2m.yaml` or specified with `--config`
Development	`./e2m.yaml` (current directory)

Verifying Installation

Check the Web Interface

Open your browser and navigate to:

http://localhost:8080

You should see the energy2mqtt web interface with API documentation.

Check Logs

Docker:

docker logs -f energy2mqtt

Systemd:

sudo journalctl -u energy2mqtt -f

Check MQTT Messages

Use an MQTT client to verify messages are being published:

# Using mosquitto_sub
mosquitto_sub -h localhost -t "homeassistant/#" -v

# Or for all energy2mqtt messages
mosquitto_sub -h localhost -t "energy2mqtt/#" -v

Updating

Docker

# Pull latest image
docker pull ghcr.io/energy2mqtt/energy2mqtt:latest

# Restart container
docker compose down
docker compose up -d

Binary

# Stop service
sudo systemctl stop energy2mqtt

# Download new binary
sudo wget -O /opt/energy2mqtt/energy2mqtt https://energy2mqtt.org/download/stable/energy2mqtt

# Restart service
sudo systemctl start energy2mqtt

From Source

cd energy2mqtt
git pull
cargo build --release
# Copy new binary to installation location

Troubleshooting

Container Won’t Start

Check logs:

docker logs energy2mqtt

Common issues:

Missing or invalid e2m.yaml
MQTT broker not reachable
Port 8080 already in use

Cannot Connect to MQTT Broker

Verify broker host and port
Check firewall rules
Verify credentials
Ensure MQTT broker is running

Permission Denied Errors

On SELinux systems:

# For Docker
sudo chcon -Rt svirt_sandbox_file_t ~/energy2mqtt/config

# For Podman (use :Z suffix on volume mounts)
podman run -v ./config:/config:Z ...

High Memory Usage

Check for message floods from meters
Verify update_interval settings
Consider reducing connected devices

Details

If running in production, always set resource limits:

# docker-compose.yaml
services:
  energy2mqtt:
    deploy:
      resources:
        limits:
          memory: 256M