This guide will walk you through the process of setting up Home Assistant and MQTT using a Portainer stack. Portainer is a lightweight management UI that allows you to easily manage Docker environments, including stacks. Home Assistant is a popular open-source home automation platform, and MQTT is a lightweight messaging protocol often used in IoT applications.
—
Prerequisites
—
Prerequisites
1. A server or machine running Docker: This could be a Raspberry Pi, a NAS, or any Linux-based system.
2. Portainer installed: If you haven’t installed Portainer yet, follow the official [Portainer installation guide](https://docs.portainer.
3. Basic knowledge of Docker and YAML: Familiarity with Docker concepts and YAML syntax will be helpful.
—
Step 1: Access Portainer
—
Step 1: Access Portainer
1. Open your web browser and navigate to your Portainer instance (e.g., `http://<your-server-ip>:9000`
2. Log in with your credentials.
—
Step 2: Create a New Stack
1. In the Portainer dashboard, go to Stacks in the left-hand menu.
2. Click Add Stack.
3. Give your stack a name (e.g., `home-automation`).
—
Step 3: Define the Stack in YAML
In the Web editor section, paste the following YAML configuration. This stack will deploy both Home Assistant and an MQTT broker (Eclipse Mosquitto).
version: '3.8'
services:
homeassistant:
image: homeassistant/home-assistant:stable
container_name: homeassistant
volumes:
- /path/to/your/homeassistant/config:/config
environment:
- TZ=UTC
restart: unless-stopped
ports:
- "8123:8123"
networks:
- home-automation
mosquitto:
image: eclipse-mosquitto:latest
container_name: mosquitto
volumes:
- /path/to/your/mosquitto/config:/mosquitto/config
- /path/to/your/mosquitto/data:/mosquitto/data
- /path/to/your/mosquitto/log:/mosquitto/log
ports:
- "1883:1883"
- "9001:9001"
restart: unless-stopped
networks:
- home-automation
networks:
home-automation:
driver: bridge
---
Step 4: Customize the Configuration
1. Replace `/path/to/your/homeassistant/
2. Replace `/path/to/your/mosquitto/
3. Time Zone: Adjust the `TZ` environment variable to match your time zone (e.g., `TZ=America/New_York`).
—
Step 5: Deploy the Stack
1. Scroll down and click Deploy the stack.
2. Portainer will pull the Docker images and start the containers. This may take a few minutes.
—
Step 6: Access Home Assistant and MQTT
1. Home Assistant:
– Open your browser and navigate to `http://<your-server-ip>:8123`
– Follow the on-screen instructions to complete the Home Assistant setup.
2. MQTT Broker:
– The MQTT broker will be available at `mqtt://<your-server-ip>:1883`
– You can configure MQTT in Home Assistant by going to Settings > Integrations > MQTT.
—
Step 7: Configure MQTT in Home Assistant
1. In Home Assistant, go to Settings > Integrations.
2. Click Add Integration and search for MQTT.
3. Enter the MQTT broker details:
– Broker: `<your-server-ip>`
– Port: `1883`
– (Optional) Add a username and password if you’ve configured authentication in Mosquitto.
—
Step 8: Verify the Setup
1. Test your MQTT connection by publishing a message to a topic using an MQTT client (e.g., [MQTT Explorer](http://mqtt-
2. Check if Home Assistant receives the message by creating an MQTT sensor in your configuration.
—
Optional: Secure Your MQTT Broker
1. Edit the Mosquitto configuration file (located in `/path/to/your/mosquitto/
2. Add authentication by creating a password file:
“`bash
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd <username>
“`
3. Update the Mosquitto configuration file to require authentication:
“`plaintext
allow_anonymous false
password_file /mosquitto/config/passwd
“`
—
Troubleshooting
– Home Assistant not starting: Check the logs in Portainer for errors. Ensure the configuration path is correct and accessible.
– MQTT connection issues: Verify the broker is running and the correct IP/port is used. Check the Mosquitto logs for errors.
—
Congratulations! You’ve successfully set up Home Assistant and MQTT using a Portainer stack. You can now start automating your smart home devices!
