kosdk/geekmagic-controller repository overview

⁠GeekMagic Controller

Lightweight MQTT-to-HTTP bridge for smalltv-ultra devices. Loads YAML configuration, subscribes to an MQTT broker, and forwards certain device commands as HTTP GET requests.

⁠Config

When the container starts it will check /config/config.yaml (this is the default argument). Map your host folder containing the file into /config in the container so it can be configured at runtime. If you mount a config folder, ensure config.yaml exists in that host folder.

⁠Secrets & Environment variables

For secure deployments, you should avoid embedding credentials in config.yaml when possible. The controller supports two environment-based ways to provide the MQTT password:

• MQTT_PASSWORD_FILE — the path to a file that contains the MQTT password. This is useful for Docker secrets or mounted files. If the file does not exist the application will fail to start with an explicit error.
• MQTT_PASSWORD — a plain environment variable containing the MQTT password.

Precedence (higher to lower): MQTT_PASSWORD_FILE > MQTT_PASSWORD > the mqtt.password field in config.yaml.

⁠Examples

Use an environment variable:

docker run --rm -v /path/to/config:/config -e MQTT_PASSWORD=super-secret gm-controller:latest

Use a secret file (bind-mounted or Docker secret):

docker run --rm \
  -v /path/to/config:/config \
  -v /path/to/mqtt_password:/run/secrets/mqtt_password \
  -e MQTT_PASSWORD_FILE=/run/secrets/mqtt_password \
  gm-controller:latest

With Docker Compose (example):

version: '3.7'
services:
  gm-controller:
    image: gm-controller:latest
    volumes:
      - ./config:/config
    secrets:
      - mqtt_password
    environment:
      - MQTT_PASSWORD_FILE=/run/secrets/mqtt_password

secrets:
  mqtt_password:
    file: ./mqtt_password

Note: MQTT_PASSWORD_FILE is preferred for security reasons since the file contents are not visible in process environment or Docker inspect output.

⁠License

BSD 3-Clause License

⁠AI Assistance

Vibe coded by Raptor mini (Preview), with human "assistance".