TrueNAS Scale Setup

TrueNAS SCALE Setup

Follow these steps to run the PowerMeter Hub Server as a custom multi-container application on TrueNAS SCALE.

These instructions require TrueNAS SCALE 24.10 or newer, which uses the Docker-based Apps backend and supports Docker Compose YAML. They do not apply to TrueNAS CORE.

The Efergy hub is hard-coded to use HTTPS on TCP port 443. This guide gives the application a dedicated IP alias so it does not take port 443 away from the TrueNAS management interface.

Prerequisites

• TrueNAS SCALE 24.10 or newer with an Apps pool configured.
• One unused static address on the same LAN as TrueNAS. This guide uses 10.0.0.213.
• A fixed management address for TrueNAS. This guide uses 10.0.0.200.
• A local DNS server that can override the Efergy sensornet.info hostname, such as Pi-hole, AdGuard Home, dnsmasq, or pfSense.
• Optional: an MQTT broker if MQTT or Home Assistant discovery will be enabled.

Example values used below:

Setting	Example
TrueNAS management IP	10.0.0.200
PowerMeter application IP	10.0.0.213
Network prefix	/24
Storage pool	tank
Persistent data path	/mnt/tank/powermeter-hub-data

Reserve both addresses outside the DHCP pool. Replace every example with values from your network.

The legacy-nginx service deliberately supports obsolete SSLv3 clients. Keep this deployment on a trusted LAN or isolated IoT VLAN and do not expose TCP port 443 to the Internet.

1. Create persistent storage

1. Go to Datasets (or Storage -> Datasets, depending on the SCALE release).
2. Select the pool that stores application data.
3. Click Add Dataset.
4. Enter powermeter-hub-data as the name.
5. Select the Apps dataset preset, then save.

The resulting path is /mnt/<pool>/powermeter-hub-data, for example /mnt/tank/powermeter-hub-data. TrueNAS recommends a separate host-path dataset for persistent application data rather than storing it only in the internal Apps dataset. See Setting Up Storage.

2. Add a dedicated IP alias

Changing network settings can interrupt access to TrueNAS. Have console or IPMI access available before continuing.

1. Go to System -> Network.
2. Edit the active interface that owns the TrueNAS management address.
3. Under Aliases or Static IP Addresses, add the unused application address and prefix, for example 10.0.0.213/24.
4. Save, click Test Changes, confirm that the management UI still opens, then make the change permanent.

TrueNAS documents this process in Configuring Interfaces.

Next, prevent the management web server from claiming port 443 on every address:

1. Go to System -> General Settings.
2. In the GUI card, click Settings.
3. Set Web Interface IPv4 Address to the management address, 10.0.0.200 in this example, instead of 0.0.0.0 or the application alias.
4. Save and reconnect to the management address if prompted.

Do not select the PowerMeter application address for the TrueNAS GUI. The TrueNAS General Settings documentation describes the web interface binding and HTTPS port options.

3. Install the custom application

1. Open Apps and select or configure an Apps pool if prompted.
2. Open Discover Apps.
3. Open the three-dot menu and select Install via YAML.
4. Enter powermeter-hub-server as the application name.
5. Paste the Compose YAML below into Custom Config.

TrueNAS documents this workflow in Installing Custom Apps.

Before saving, change both values that depend on your system:

• /mnt/tank/powermeter-hub-data to the dataset path created in step 1.
• 10.0.0.213 to the dedicated application alias created in step 2.

Also update the timezone, voltage, power factor, MQTT settings, and DEVICE_URL.

services:
  hub-server:
    image: ghcr.io/devoldschool/powermeter_hub_server/hub-server:latest
    restart: unless-stopped
    volumes:
      - /mnt/tank/powermeter-hub-data:/app/data:rw
    environment:
      TZ: "Australia/Brisbane"
      LOG_LEVEL: "INFO"
      # Common mains voltages: AU/UK = 230, US = 120
      MAINS_VOLTAGE: "230"
      # H1/H2 hubs use 0.6; H3 hubs use 1.0
      POWER_FACTOR: "0.6"
      # Number of months to retain; 0 keeps everything
      HISTORY_RETENTION_MONTHS: "0"
      MQTT_ENABLED: "false"
      MQTT_BROKER: "homeassistant.local"
      MQTT_PORT: "1883"
      # MQTT_USER: "mqtt-user"
      # MQTT_PASS: "change-me"
      HA_DISCOVERY: "false"
      ENERGY_MONTHLY_RESET: "false"
      # Optional link shown in Home Assistant device information
      DEVICE_URL: "https://10.0.0.200"

  legacy-nginx:
    image: ghcr.io/devoldschool/powermeter_hub_server/legacy-nginx:latest
    restart: unless-stopped
    ports:
      - "10.0.0.213:443:443"
    depends_on:
      - hub-server

The published legacy-nginx image already contains the compatibility Nginx configuration and self-signed certificate required by the old hub. Only the SQLite data directory needs a persistent host-path mount.

Click Save and wait for the application state to become Running.

4. Verify the application

Select the installed application and inspect the workload status and logs. Both the hub-server and legacy-nginx containers should be running.

From another computer on the LAN, run:

curl -k https://10.0.0.213/check_key.html

The expected response is:

success

The -k option is expected because the compatibility proxy uses a self-signed certificate.

5. Redirect the Efergy hub with local DNS

Create local DNS records that resolve the hostname used by the hub to the dedicated application address, 10.0.0.213 in this example.

Hub version	Local DNS records
H1	<device-mac>.sensornet.info and <device-mac>.keys.sensornet.info
H2	<device-mac>.h2.sensornet.info
H3	<device-mac>.h3.sensornet.info

Examples:

Domain	Address
aa.bb.cc.dddddd.sensornet.info	10.0.0.213
aa.bb.cc.dddddd.keys.sensornet.info	10.0.0.213
41.0a.04.001ec0.h2.sensornet.info	10.0.0.213

Check the result from another LAN device, specifying your local DNS server if necessary:

nslookup 41.0a.04.001ec0.h2.sensornet.info <DNS_SERVER_IP>

Power-cycle the Efergy hub after the DNS record is active, then follow the hub-server logs in the TrueNAS Apps screen.

The server logs the detected hub version after the first packet. Set POWER_FACTOR to 0.6 for H1/H2 or 1.0 for H3, save the edited YAML, and allow TrueNAS to redeploy the application.

Updating and backups

• Use the update action in the TrueNAS Apps screen when a new container image is available. If necessary, edit and save the custom application to redeploy the latest images.
• Create regular ZFS snapshots or replication tasks for the powermeter-hub-data dataset. The SQLite database is stored there and survives application replacement.
• Before deleting the application, confirm that any option to remove application storage does not target the host-path dataset.

Troubleshooting

Application deployment reports that port 443 is already allocated

• Confirm 10.0.0.213 is configured as a TrueNAS interface alias.
• Confirm the TrueNAS GUI is bound only to the management address, not 0.0.0.0 and not 10.0.0.213.
• Confirm no other app or service is bound to 10.0.0.213:443.
• Do not change the PowerMeter host port to 8443; the Efergy hub expects port 443.

The data directory reports permission denied

Edit the dataset permissions and grant the TrueNAS apps group (GID 568) Modify access, then redeploy the app. Do not make an unrelated shared dataset world-writable.

The containers run but no readings arrive

• Confirm the hub's exact hostname resolves to the application alias from the same DNS server used by the hub.
• Confirm TCP port 443 is allowed from the hub's VLAN to the application alias.
• Set LOG_LEVEL to DEBUG, save the YAML, and inspect the new logs.
• Power-cycle the hub after changing DNS.
• If MQTT is enabled, separately confirm TrueNAS Apps can reach the broker on TCP port 1883.

TrueNAS CORE or an older SCALE release is installed

Do not install or replace the system Docker runtime manually. Upgrade to a supported TrueNAS SCALE release, or run the application in a small Debian VM/LXC on Proxmox instead.