Environment Setup

Running Home Assistant in Docker requires network configuration that allows the container to appear as a standalone device on the network. This setup uses macvlan to assign a dedicated IP address to the Home Assistant container.

Known Issues

Several installation attempts failed:

• Native CentOS 7 installation encountered dependency conflicts
• CentOS 8 did not resolve the underlying issues
• Docker/podman on CentOS 8 had permission problems preventing proper port listening, making device integration impossible
• Incorrect domain selection during Apple Home setup results in hundreds of unwanted entities appearing

For Apple Home integration cleanup: navigate to Home Settings → Home Hub & Bridges → locate the HASS bridge entry → remove it. Standard uninstal or reset options do not work for this.

Installation Procedure

Environment: CentOS 7 with Docker

Installing Docker

# Remove existing container runtimes
sudo yum remove -y docker* containerd.io podman*
sudo rm -rf /var/lib/docker
sudo rm -rf /etc/docker

# Configure Aliyun Docker repository
sudo tee /etc/yum.repos.d/docker-ce.repo <<-'EOF'
[docker-ce-stable]
name=Docker CE Stable - $basearch
baseurl=https://mirrors.aliyun.com/docker-ce/linux/centos/7/$basearch/stable
enabled=1
gpgcheck=0 
repo_gpgcheck=0
gpgkey=https://mirrors.aliyun.com/docker-ce/linux/centos/gpg
EOF

# Install required tools
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# Install Docker components
sudo yum install -y --nogpgcheck \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

# Enable and start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Verify installation
sudo docker version

Configuring macvlan Network

Replace network values with actual infrastructure details. Check the host interface using ip link to determine the parent interface name (e.g., enp1s0, eth0).

# Create macvlan network
# Adjust: host IP, gateway, subnet, and interface to match environment
sudo docker network create -d macvlan \
  --subnet=192.168.0.0/24 \
  --gateway=192.168.0.1 \
  --ip-range=192.168.0.200/32 \
  -o parent=eth0 \
  -o macvlan_mode=bridge \
  --aux-address="host_reserved=192.168.0.114" \
  macvlan_net

# Verify network creation
docker network ls
docker network inspect macvlan_net

Deploying Home Assistant Container

# Create config directory
mkdir -p ~/homeassistant/config

# Pull image (using alternative registry for reliability)
docker pull ghcr.io/home-assistant/home-assistant:stable

# Launch container
docker run -d \
  --name homeassistant \
  --network macvlan_net \
  --restart unless-stopped \
  --privileged \
  -v /etc/localtime:/etc/localtime:ro \
  -v ~/homeassistant/config:/config \
  -e TZ=Asia/Shanghai \
  ghcr.io/home-assistant/home-assistant:stable

Note: macvlan mode is incompatible with host netwroking. The container requires its own dedicated IP on the network segment.

Firewall Configuration

# Open mDNS and SSDP ports for device discovery
sudo firewall-cmd --permanent --add-port=5353/udp
sudo firewall-cmd --permanent --add-port=1900/udp

# Open Home Assistant web interface port
sudo firewall-cmd --permanent --add-port=8123/tcp

# Apply changes
sudo firewall-cmd --reload

Post-Installation Notes

After initial setup, disable unused entities in the device configuration to prevent clutter in Apple Home.

HACS can be restored from a backup file if available.

For Apple Home integration issues, trial-and-error with actual device pairing is more reliable than following AI-generated port configuration suggestions.

Reserve the assigned IP in the router's DHCP settings to prevent lease expiration and IP conflicts.