-
Notifications
You must be signed in to change notification settings - Fork 15
Built‐in Components and Automation
The system includes built-in components and automation for continuous operation and extensibility.
Several container definitions are provided out-of-the-box as examples, illustrating common infrastructure services and extension points:
-
libs/broker– A container running an MQTT broker (Eclipse Mosquitto) for IoT messaging. On deployment, it auto-configures a user (from the global credentials) and publishes its broker URI as an environment variable (broker) for other containers to consume. The broker persists message data and logs under /app/broker. -
libs/bridge- A Zigbee IoT bridge container for Zigbee2MQTT. It installs the Zigbee2MQTT service (using Node.js and pnpm), bridging a Zigbee network to the MQTT broker. The Zigbee coordinator USB device is passed into the container via the MOUNT setting. The container automatically reloads configuration and restores data from snapshots if present. -
libs/assistant– Installs Home Assistant in an isolated Python virtual environment and sets up an optional web file editor (Configurator). The container is configured to restore its data directory from the latest snapshot on startup, preserving configuration between updates. -
libs/share– A network file share container (Samba). It creates a Samba share at /share, accessible with the same global credentials (added as a Samba user). Other containers can mount this share for persistent storage by setting their MOUNT=share. When a container’s MOUNT is set to include share, the deployment pipeline automatically treats it as a CIFS mount and ensures the container is run in a privileged mode to allow mounting. -
libs/proxy– A reverse proxy container (Caddy) that dynamically maps container hostnames to their IP addresses. It queries Proxmox for all LXC instances and generates a Caddy configuration to forward .lan requests to the respective container’s IP. Logging is enabled per host under /app/proxy/logs.
The control plane continuously monitors and updates the environment state through a dedicated tasks pipeline. Scripts placed in the tasks directory are automatically converted into separate Gitea repositories (under the tasks organisation) with scheduled CI workflows. A built-in example is the health task, which runs periodically (every 30 minutes) to query all LXC containers via the Proxmox API. It records each container’s status and IP address as environment variables (under a health context) and updates the repository description of each container with its current state (e.g. running or stopped) and a direct link to its Proxmox console. Additional custom tasks can be added similarly, using a cron schedule comment (e.g. # ! cron '*/30 * * * *') in the task script to define execution frequency.
The embedded Gitea interface is automatically tailored to the GitOps workflow. On initialisation, all created repositories have nonessential features disabled (issues, wiki, projects, etc.), focusing the interface on code and automation. Custom styles and templates are applied to the Gitea web UI to streamline usage: navigation items for unused sections are hidden, and the header is branded with the Proxmox-GitOps label. Quick-access links to key repositories and organisations (e.g. the main monorepository and task overview) are injected into the top navigation. This UI customisation occurs via the config::customize recipe, which deploys CSS and HTML templates into Gitea’s custom directories. Together, these interface adjustments ensure the web UI cleanly reflects the state and controls of the Proxmox-GitOps environment.
#generated