cerealcable/genmon repository overview

⁠genmon

genmon⁠ monitors and controls Generac (and some other) generators over their serial or Modbus interface. It has a web UI, email and SMS alerts, MQTT, Home Assistant and a long list of add-ons.

This image runs genmon on Debian with its Python dependencies locked. It is built from tagged genmon releases only: a new image tag means a new genmon release, not a scheduled rebuild.

• Built from the commit that each upstream release tag points at
• Python dependencies locked, with a 10-day cooldown on new package releases
• Smoke tested before every publish
• linux/amd64 and linux/arm64
• Signed with cosign (verify⁠)

⁠Tags

Image tags use the version genmon reports about itself (2.0.3), not the zero-padded upstream git tag (2.0.03).

⁠Quick start

With a USB serial adapter:

docker run -d --name genmon \
  -p 8000:8000 \
  --device /dev/ttyUSB0 \
  -v ./config:/etc/genmon \
  -v ./log:/var/log \
  -e TZ=America/Los_Angeles \
  cerealcable/genmon:latest

Then set port = /dev/ttyUSB0 in config/genmon.conf, restart the container, and open http://<host>:8000.

⁠Docker Compose

services:
  genmon:
    image: cerealcable/genmon:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    volumes:
      - ./config:/etc/genmon
      - ./log:/var/log
    environment:
      - TZ=America/Los_Angeles

⁠Serial over TCP

If the generator's serial port is on a network bridge (an ESP32 or a serial-to-Ethernet adapter), leave out the device and set these in genmon.conf:

use_serial_tcp = True
serial_tcp_address = 192.0.2.10
serial_tcp_port = 8899

For a Modbus TCP gateway, also set modbus_tcp = True and usually serial_tcp_port = 502.

⁠Configuration

On first start genmon copies its default configuration into /etc/genmon. Edit those files, or use the Settings page in the web UI, and restart the container. See the genmon wiki⁠ for every option and add-on.

The only change from upstream's defaults is update_check = false. With it on, genmon warns whenever its development branch is ahead of the installed release, but you update this image by pulling a newer tag. An existing genmon.conf is never modified.

genmon exits if it cannot reach the generator's serial port, and the web UI goes down with it. If the UI never comes up, check the port or use_serial_tcp settings, and log/genmon.log.

The container runs as root, like a native genmon install, because it needs the serial device. genmon has no authentication by default, so don't expose port 8000 to the internet. Put it behind a reverse proxy⁠ with auth, or turn on genmon's own login in Settings, which needs HTTPS enabled.

⁠Reverse proxy

A reverse proxy needs to get two things right for genmon:

• Give genmon its own hostname, such as genmon.example.com. The web UI links to absolute paths like / and /logout, so it can't live under a subpath like /genmon/.
• Pass the browser's Host header through, or set X-Forwarded-Host. genmon rejects any request that changes something (saving settings, starting the generator) when its Origin doesn't match one of those headers. If pages load but saving fails with a 403, check this first. genmon logs it as CSRF blocked: Origin mismatch in log/genserv.log.

The UI uses plain HTTP polling, so the proxy doesn't need websocket support. Let the proxy handle TLS and leave genmon's usehttps off. The examples below assume genmon is on the same Docker network as the proxy, reachable as genmon:8000, so you can drop the ports: mapping.

⁠Caddy

Caddy passes Host through by default:

genmon.example.com {
	reverse_proxy genmon:8000
}

⁠Traefik

Traefik passes Host through by default. As labels on the genmon service:

services:
  genmon:
    image: cerealcable/genmon:latest
    labels:
      traefik.enable: "true"
      traefik.http.routers.genmon.rule: Host(`genmon.example.com`)
      traefik.http.routers.genmon.entrypoints: websecure
      traefik.http.routers.genmon.tls.certresolver: letsencrypt
      traefik.http.services.genmon.loadbalancer.server.port: "8000"
    networks:
      - proxy

networks:
  proxy:
    external: true

Swap websecure, letsencrypt and proxy for your own entrypoint, certificate resolver and network names. To require a login, add your auth middleware (Authelia, Authentik or basic auth) with traefik.http.routers.genmon.middlewares.

⁠nginx

nginx replaces Host with the upstream address unless told otherwise, which breaks saving settings:

server {
    listen 443 ssl;
    server_name genmon.example.com;

    ssl_certificate     /etc/ssl/genmon.example.com.crt;
    ssl_certificate_key /etc/ssl/genmon.example.com.key;

    location / {
        proxy_pass http://genmon:8000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The Home Assistant and Hubitat add-ons run their own API servers on separate ports. Proxy those separately if you use them; the web UI proxy doesn't cover them.

⁠Verifying the image

Images are signed with cosign. Save this public key as cerealcable.pub:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExjdgFfwLu7CHXs9+z+v7oCsWY4mo
khNFQ6ww0cKxCZR3HndkaKftoiGAgzitBQ13fL2ZPxobUv5HicDnL4idMg==
-----END PUBLIC KEY-----

Then:

cosign verify --key cerealcable.pub cerealcable/genmon:latest

⁠License

genmon is licensed under GPL-2.0⁠, and its complete source is in the image at /app/genmon. The build files for this image are MIT-licensed. This image is maintained by cerealcable and is not affiliated with the genmon project. Please report genmon bugs upstream⁠.