Running EnergyWizard behind your own Home Assistant address

Installation, advanced

Running Home Assistant OS or Supervised? Use HA's own Ingress instead - install EnergyWizard as an add-on and you get auth/TLS/routing for free, simpler and safer than everything below. This guide is for Container installations WITHOUT Supervisor (the most common way to run HA in plain Docker) - Ingress doesn't exist there, so this is the only way to get the same result: EnergyWizard under the exact same address as your HA.

What you get

A new, optional ha-gateway service in EnergyWizard's own docker-compose.yml that merges your Home Assistant and EnergyWizard under the same address: everything else passes through to your real HA, /energywizard goes to the web dashboard, /energywizard/mobil and /tablet go to the mobile app.

Two valid end states - pick whichever suits you:

Its own port (simplest, recommended for most): leave the gateway on its own port (e.g. 8199) next to your HA, which always stays on 8123 - the same pattern as other standalone services. Never touches HA's own configuration. Just go through Steps 1-2 below, skip Step 3.
The exact same port as HA (Step 3, more work): move HA's own port aside so the gateway can take over 8123 entirely - requires you to change HA's own configuration and restart your home control system yourself. Only worth it if you really want the EXACT same address/port as HA, not just the same domain.

Step 1 - configure

Add to your .env (example in .env.example):

HA_GATEWAY_DOMAIN=your-domain.com
HA_GATEWAY_CERT_DIR=/path/to/your/cert/dir
HA_GATEWAY_UPSTREAM_HOST=192.168.1.X   # your HA's local IP
HA_GATEWAY_UPSTREAM_PORT=8123
HA_GATEWAY_UPSTREAM_PROTO=https        # http if your HA doesn't terminate its own TLS
HA_GATEWAY_PORT=8199                   # TEST PORT - not your real 8123 yet

HA_GATEWAY_CERT_DIR must contain real fullchain.pem/privkey.pem files. If you use Certbot these may be symlinks pointing outside the directory (common) - a simple directory mount won't resolve them. Fix it with a local docker-compose.override.yml (never committed, see .gitignore) mounting the real files directly:

services:
  ha-gateway:
    volumes:
      - /path/to/archive/yourdomain/fullchain1.pem:/certs/fullchain.pem:ro
      - /path/to/archive/yourdomain/privkey1.pem:/certs/privkey.pem:ro

Step 2 - test on a completely different port FIRST

docker compose --profile ha-gateway up -d ha-gateway and visit https://your-nuc-ip:8199/ (should show your normal HA login) and /energywizard/ (should show EnergyWizard). Do NOT touch your real port 8123 until both work perfectly here - including logging into EnergyWizard and HA's live updates (click around a bit) working as usual.

Step 3 - move HA's own port (you do this YOURSELF, manually)

EnergyWizard's installation never touches your HA's own configuration - you do that yourself, in HA's own interface (Settings → System → Network, requires "Advanced mode" enabled on your user profile). Move HA's "server port" away from 8123 (e.g. to 8124) and save - HA restarts. Then set HA_GATEWAY_UPSTREAM_PORT to the same new port and HA_GATEWAY_PORT to 8123, and restart the gateway. Now your-domain.com:8123 is the gateway, which in turn talks to your HA on its new internal port.

Safety net: test thoroughly before closing off any other paths to your HA (the mobile app, any voice assistants) - they often point to the old port hardcoded and need updating. Make the change when you have plenty of time to troubleshoot on site, not right before heading out.