ESPHome Infrastructure Management

This repository uses a GitOps-driven workflow to manage, validate, and deploy ESPHome devices using localized network routing and encrypted secrets management.

Architecture Overview

• Security Best Practices: All recommendations from the official ESPHome Security Best Practices documentation have been fully implemented.
• Zero mDNS Dependency: All devices have mDNS disabled for enhanced security and lower network overhead.
• DNS Resolution: Network tracking relies on static DHCP reservations assigned at the router level. Devices communicate via local DNS hostnames (mapped via use_address).
• Optimized Logging: To save disk I/O on the centralized log server and protect sensitive network tokens, wifi and api log components are restricted to WARN level.

---

Secrets Management

Secrets (Wi-Fi credentials, API keys, etc.) are encrypted at rest in the repository within the secrets.enc.yaml file using age.

• CI Pipelines: Parse the structure of secrets.enc.yaml to identify the required keys, automatically generating a dummy secrets.yaml where all values are replaced with placeholders. This documents the required configuration while validating builds safely without exposing production keys.
• Production Deployment: Requires the target decryption key to decrypt secrets.enc.yaml and generate the live production secrets.yaml.

---

Workflows

Continuous Integration (CI)

Every commit and Pull Request (including automated dependency updates) triggers the CI pipeline to ensure structural integrity:

1. Runs linters to validate the code quality and syntax across the codebase.
2. Generates dummy secrets from the structure of secrets.enc.yaml.
3. Compiles the firmware images to guarantee the build succeeds.

Local Deployment

Deployments are currently managed locally from a deployment machine with network access to the IoT infrastructure.

1. Decrypt and Build Firmwares

To decrypt production secrets and compile the production binaries, provide the path to your private age key:

KEY=/path/to/your/production.key make

2. Deploy to Production (OTA)

Once the binaries are built, upload them Over-The-Air and reboot the target devices:

make install