The Home Assistant Docker image provides a reliable way to run your smart home hub inside a container. This approach simplifies deployment, updates, and isolation on various host systems.
Below you will find key technical details, configuration options, and operational guidance tailored for both new users and teams managing larger setups.
| Image Name | Architectures | Default Port | Data Persistence Path |
|---|---|---|---|
| homeassistant/home-assistant | amd64, arm64, arm/v7 | 8123 | /config |
| homeassistant/home-assistant-dev | amd64, arm64 | 8123 | /config |
| homeassistant/home-assistant-supervised | amd64, arm64 | 8123 | /config |
| homeassistant/raspberrypi4-homeassistant | arm64, arm/v7 | 8123 | /config |
Running Home Assistant in Docker
Using the official Home Assistant Docker image streamlines container creation and ensures compatibility with add-ons and core updates. You can map the configuration directory to a host volume so that your integrations and automations survive container restarts.
Network settings require attention, especially when you plan to integrate Zigbee2MQTT or other USB-based devices. Assigning the correct device paths and capabilities helps avoid permission issues and connection drops.
Image Variants and Tags
The project provides multiple image variants to match different environments and use cases. Selecting the right variant reduces resource usage and avoids unnecessary components on constrained hosts.
Review tags carefully before deploying production instances, as stable releases differ from nightly builds and development branches. Pinning tags or digest values enhances reproducibility and rollback reliability.
Configuration and Data Persistence
Persistent storage is critical for retaining core configurations, recordings, and long-term statistics. Mounting a host directory to /config ensures that your setup remains intact across image updates and node changes.
Environment variables can adjust timezones and optimize internal services. Careful planning of these parameters early on reduces future maintenance and simplifies migration between hosts or clusters.
Advanced Networking and Add-ons
Incorporating add-ons via the supervised variant often requires additional networking rules and port mappings. Defining clear policies for inbound and outbound traffic keeps the system secure while preserving add-on functionality.
Service discovery, HTTP reverse proxying, and TLS termination are common topics when you centralize multiple stacks. Aligning these patterns with Home Assistant ports and network interfaces simplifies troubleshooting and monitoring.
Operational Best Practices and Recommendations
- Pin image tags or digests to ensure reproducible builds across environments.
- Back up the /config directory regularly and test restoration procedures.
- Monitor resource usage, especially when adding numerous integrations or automations.
- Update images in a controlled staging environment before rolling out to production.
- Use version control for core configuration files to track changes over time.
- Document network, volume, and device mappings to simplify migrations and team handovers.
FAQ
Reader questions
How do I map the Home Assistant config directory correctly on Linux?
Use a volume mount such as -v /srv/homeassistant:/config and ensure the target directory has sufficient permissions for the container user to read and write configuration files.
What hardware requirements should I consider before running the Home Assistant Docker image?
For a typical local installation, 2 CPU cores, 4 GB of RAM, and fast storage for the /config volume provide smooth operation with multiple integrations and background tasks.
Can I run the supervised image without Docker Supervised mode?
The supervised image is designed for environments that support Docker Service commands; using it outside of Docker Swarm or similar orchestrators may lead to unexpected behavior and missing features. Place both containers on the same Docker network, grant the Zigbee2MQTT container access to the USB device, and configure the integration in Home Assistant via the MQTT discovery or manual integration setup.