add documentation

.github/workflows/check-code-quality.yml

@@ -1,10 +1,12 @@
 ---
 name: "Check code quality"
 
 on:
   pull_request:
     branches:
       - "master"
+    paths-ignore:
+      - '**.md'
 
 jobs:
   lint:

.github/workflows/test-ubuntu-lts.yml

@@ -1,14 +1,18 @@
 ---
 name: "Test (Ubuntu 22.04)"
 
 on:
   pull_request:
     branches:
       - "master"
+    paths-ignore:
+      - '**.md'
 
   push:
     branches:
       - "master"
+    paths-ignore:
+      - '**.md'
 
   schedule:
     - cron: "0 7 * * 0"

README.md

@@ -1,5 +1,64 @@
-[![Test (Ubuntu 22.04)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml/badge.svg?event=push)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml)
+# Ansible Collection - Smarthome
+
 [![Ansible Galaxy](https://img.shields.io/badge/collection-artyorsh.smarthome-blue)](https://galaxy.ansible.com/artyorsh/smarthome)
+[![Test (Ubuntu 22.04)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml/badge.svg?event=push)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml)
+
+Effortlessly connect your IoT infrastructure to Apple Home ✨
+
+## Description
+
+This collection is a set of Ansible roles, aiming to simplify the deployment and configuration
+of [HomeAssistant](https://home-assistant.io),
+[Zigbee2MQTT](https://www.zigbee2mqtt.io)
+and [Mosquitto](https://mosquitto.org),
+making them ready to connect to Apple Home.
+
+## Requirements
+
+- A [ZigBee Adapter](https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites).
+- Docker. Please refer to [ansible-role-docker](https://github.com/geerlingguy/ansible-role-docker?tab=readme-ov-file#ansible-role-docker) to install it with Ansible.
+
+## Installation
+
+```
+ansible-galaxy collection install artyorsh.smarthome
+```
+
+## Usage
+
+1. [Find the ZigBee adapter](https://www.zigbee2mqtt.io/guide/getting-started/#installation)
+2. [Run the playbook](#example-playbook)
+3. Open HomeAssistant frontend and complete the setup (localhost:8123)
+4. [Enable the MQTT integration](https://www.home-assistant.io/integrations/mqtt/#broker-configuration) (broker: "mosquitto", port: 1883)
+5. Open Zigbee2MQTT frontend and pair the devices (localhost:8124)
+6. Restart HomeAssistant
+7. [Pair with Apple Home](https://www.home-assistant.io/integrations/homekit/#setup) (starting from step 1)
+
+For a real-world usage example, see my [infra playbooks](https://github.com/artyorsh/infra).
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+
+  vars:
+    smarthome_zigbee_adapter: /dev/ttyUSB0
+    smarthome_user: { name: "myuser", password: "changeme" }
+    # homeassistant_mdns_host_network_interface: wlan0 # running on wlan?
+
+  roles:
+    - artyorsh.smarthome.smarthome
+```
+
+By default, HomeAssistant and Zigbee2MQTT containers are deployed on ports 8123 and 8124.
+
+## Configuration
+
+- The [smarthome role](./roles/smarthome/README.md) is a shortcut to deploy everything in one go
+- Please refer to the role documentation pages for more configuration options:
+  - [homeassistant](./roles/homeassistant/README.md)
+  - [zigbee2mqtt](./roles/zigbee2mqtt/README.md)
+  - [mosquitto](./roles/mosquitto/README.md)
 
 ## License
 

galaxy.yml

@@ -10,7 +10,7 @@
 authors:
   - artyorsh
 
-description: your collection description
+description: Simplify the deployment and configuration of HomeAssistant, Zigbee2MQTT and Mosquitto, making them ready to connect to Apple Home.
 
 license:
   - MIT

roles/homeassistant/README.md

@@ -0,0 +1,84 @@
+# smarthome.homeassistant
+
+Installs the [lscr.io/linuxserver/homeassistant](https://hub.docker.com/r/linuxserver/homeassistant) image. Modifies the Dockerfile to enable avahi-tools.
+
+[Why to modify the Dockerfile?](#why-to-modify-the-dockerfile)
+
+## Role Variables
+
+- `homeassistant_port`
+  - Default: `8123`
+  - Description: The port on which HomeAssistant will be accessible.
+  - Type: int
+  - Required: no
+- `homeassistant_network`
+  - Default: `homeassistant`
+  - Description: The name of the Docker network.
+  - Type: str
+  - Required: no
+- `homeassistant_install_dir`
+  - Default: `/opt/docker/homeassistant`
+  - Description: The directory where HomeAssistant will be installed.
+  - Type: str
+  - Required: no
+- `homeassistant_env`
+  - Default: `{}`
+  - Description: Docker container environment variables. See [linuxserver/homeassistant](https://docs.linuxserver.io/images/docker-homeassistant/#environment-variables-e).
+  - Type: dict
+  - Required: no
+- `homeassistant_config`
+  - Default: See [homeassistant_config_default](./vars/main.yml)
+  - Description: Configuration for [configuration.yaml](https://home-assistant.io/docs/configuration/).
+  - Type: dict
+  - Required: no
+- `homeassistant_homekit_config`
+  - Default: See [homeassistant_homekit_config_default](./vars/main.yml)
+  - Description: Configuration for the [HomeKit integration](https://www.home-assistant.io/integrations/homekit).
+  - Type: dict
+  - Required: no
+- `homeassistant_mdns_host_network_interface`
+  - Default: `eth0`
+  - Description: The host network interface from which mDNS requests are sent to the HomeAssistant container.
+  - Type: str
+  - Required: no
+
+## Dependencies
+
+- [community.docker](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html)
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+
+  roles:
+    - artyorsh.smarthome.homeassistant
+```
+
+### Only include specific HomeAssistant entries
+
+```yaml
+- hosts: localhost
+
+  vars:
+    homeassistant_homekit_config:
+      filter:
+        include_entity_globs: ["light.*"]
+
+  roles:
+    - artyorsh.smarthome.homeassistant
+```
+
+## Why to modify the Dockerfile?
+
+Running HomeAssistant in a Docker bridge network causes issues with the discoverability of the HomeKit integration by Apple Home. This is because HomeKit relies on mDNS for device discovery, which doesn't work out of the box across Docker's bridge network due to the way Docker handles networking. By [enabling Avahi tools](./templates/homeassistant-avahi-dockerfile.j2), which provide mDNS services, the HomeAssistant container can broadcast its presence on the network, making it discoverable by Apple Home. For more details, please refer to this [community thread](https://community.home-assistant.io/t/using-homekit-component-inside-docker/45409/45?page=2).
+
+### Why to run in a bridge network?
+
+Running in a bridge network provides isolation between the Docker containers and the host machine, which enhances the security of IoT infrastructure.
+It allows containers to communicate with each other while keeping them isolated from the host's network.
+
+### Is it still possible to run it in the host network?
+
+Yes, it is.
+In this case, mDNS replication and customization of HomeAssistant image are not required.

roles/mosquitto/README.md

@@ -0,0 +1,54 @@
+# smarthome.mosquitto
+
+Installs the [eclipse-mosquitto](https://github.com/eclipse/mosquitto/tree/master/docker#docker-images) image.
+
+## Role Variables
+
+- `mosquitto_version`
+  - Default: `latest`
+  - Description: The version of the Mosquitto image to install. See [published tags](https://hub.docker.com/_/eclipse-mosquitto/tags).
+  - Type: str
+  - Required: no
+- `mosquitto_port`
+  - Default: `1883`
+  - Description: The MQTT listen port.
+  - Type: int
+  - Required: no
+- `mosquitto_websocket_port`
+  - Default: `9001`
+  - Description: The MQTT WebSockets listen port.
+  - Type: int
+  - Required: no
+- `mosquitto_install_dir`
+  - Default: `/opt/docker/mosquitto`
+  - Description: The directory where Mosquitto will be installed.
+  - Type: str
+  - Required: no
+- `mosquitto_env`
+  - Default: `{}`
+  - Description: Docker container environment variables.
+  - Type: dict
+  - Required: no
+- `mosquitto_user`
+  - Default: `{ name: "{{ ansible_user }}", password: "mosquitto" }`
+  - Description: Authentication credentials for the Mosquitto instance. [See docs](https://mosquitto.org/documentation/authentication-methods).
+  - Type: dict with keys `name` (str) and `password` (str)
+  - Required: no
+
+## Dependencies
+
+- [community.docker](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html)
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+
+  vars:
+    mosquitto_user:
+      name: "mosquitto"
+      password: "changeme"
+
+  roles:
+    - artyorsh.smarthome.mosquitto
+```

roles/smarthome/README.md

@@ -0,0 +1,50 @@
+# smarthome.smarthome
+
+An all-in-one role to install [HomeAssistant](../homeassistant/readme.md), [Mosquitto](../mosquitto/readme.md), and [Zigbee2MQTT](../zigbee2mqtt/readme.md).
+
+## Requirements
+
+- A Zigbee Adapter. See [prerequisites](https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites).
+
+## Role Variables
+
+- `smarthome_network`
+  - Default: `smarthome`
+  - Description: Overrides the network for [HomeAssistant](../homeassistant/readme.md#role-variables), [Mosquitto](../mosquitto/readme.md#role-variables), and [Zigbee2MQTT](../zigbee2mqtt/readme.md#role-variables).
+  - Type: str
+  - Required: no
+- `smarthome_user`
+  - Default: `{ name: "{{ ansible_user }}", password: "smarthome" }`
+  - Description: Overrides the users for [Mosquitto](../mosquitto/readme.md#role-variables) and [Zigbee2MQTT](../zigbee2mqtt/readme.md#role-variables).
+  - Type: dict with keys `name` (str) and `password` (str)
+  - Required: no
+- `smarthome_zigbee_adapter`
+  - Default: ``
+  - Description: Specifies the ZigBee adapter. Overrides [zigbee2mqtt_adapter](../zigbee2mqtt/readme.md#role-variables).
+  - Type: str
+  - Required: yes
+
+## Dependencies
+
+- [community.docker](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html)
+
+## Example Playbook
+
+```yaml
+- role: "artyorsh.smarthome.smarthome"
+  vars:
+    smarthome_zigbee_adapter: "/dev/ttyUSB0"
+    smarthome_user: { name: "smarthome", password: "changeme" }
+```
+
+### Custom settings for individual containers
+
+```yaml
+- role: "artyorsh.smarthome.smarthome"
+  vars:
+    smarthome_zigbee_adapter: "/dev/ttyUSB0"
+    smarthome_user: { name: "smarthome", password: "changeme" }
+    homeassistant_homekit_config:
+      filter:
+        include_entity_globs: ["light.*"]
+```

roles/zigbee2mqtt/README.md

@@ -0,0 +1,67 @@
+# smarthome.zigbee2mqtt
+
+Installs the [koenkk/zigbee2mqtt](https://hub.docker.com/r/koenkk/zigbee2mqtt/) image.
+
+## Requirements
+
+- A [ZigBee Adapter](https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites).
+- An [MQTT server](../mosquitto/readme.md).
+
+## Role Variables
+
+- `zigbee2mqtt_version`
+  - Default: `latest`
+  - Description: The version of the Zigbee2MQTT image to install. See [published tags](https://hub.docker.com/r/koenkk/zigbee2mqtt/tags).
+  - Type: str
+  - Required: no
+- `zigbee2mqtt_network`
+  - Default: `zigbee2mqtt`
+  - Description: The name of the Docker network.
+  - Type: str
+  - Required: no
+- `zigbee2mqtt_port`
+  - Default: `8124`
+  - Description: The port for the Zigbee2MQTT WebUI.
+  - Type: int
+  - Required: no
+- `zigbee2mqtt_install_dir`
+  - Default: `/opt/docker/zigbee2mqtt`
+  - Description: The directory where Zigbee2MQTT will be installed.
+  - Type: str
+  - Required: no
+- `zigbee2mqtt_env`
+  - Default: `{}`
+  - Description: Docker container environment variables. See [zigbee2mqtt.io](https://www.zigbee2mqtt.io/guide/installation/02_docker.html#running-the-container).
+  - Type: dict
+  - Required: no
+- `zigbee2mqtt_config`
+  - Default: See [zigbee2mqtt_config_default](./vars/main.yml)
+  - Description: Configuration for [configuration.yaml](https://www.zigbee2mqtt.io/guide/configuration/#configuration). **Must include** [server](https://www.zigbee2mqtt.io/guide/configuration/mqtt.html#server-connection) to operate.
+  - Type: dict
+  - Required: yes
+- `zigbee2mqtt_adapter`
+  - Default: ``
+  - Description: Path to the ZigBee Adapter. See [requirements](#requirements).
+  - Type: str
+  - Required: yes
+
+## Dependencies
+
+- [community.docker](https://docs.ansible.com/ansible/latest/collections/community/docker/index.html)
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+
+  vars:
+    zigbee2mqtt_adapter: "/dev/ttyUSB0"
+    zigbee2mqtt_config:
+      mqtt:
+        server: "mqtt://mosquitto"
+        user: "mosquitto"
+        password: "changeme"
+
+  roles:
+    - artyorsh.smarthome.zigbee2mqtt
+```