Home Assistant Supervised Role

This Ansible role installs Home Assistant Supervised on Debian 12+ systems with all required dependencies, networking configuration, and proper validation.

Features

• ✅ Complete networking setup (NetworkManager + systemd-resolved)
• ✅ Docker CE installation via official methods
• ✅ OS-Agent installation with version selection
• ✅ Home Assistant Supervised installation with machine type configuration
• ✅ Comprehensive validation and error checking
• ✅ Service management and automatic startup
• ✅ Support for multiple architectures (x86_64, arm64)
• ✅ Cleanup of downloaded packages
• ✅ Proper privilege escalation and security

Requirements

BIOS Configuration Requirements

Critical BIOS settings must be configured before installation:

Essential Virtualization Settings

• Enable VT-x (Intel) or AMD-V (AMD) - Required for container virtualization
• Enable VT-d (Intel) or AMD IOMMU (AMD) - Required for hardware passthrough
• Location: Usually under "Advanced" → "CPU Configuration" or "Virtualization"

Boot Mode Configuration

• Enable UEFI boot mode - Modern container systems require UEFI
• Disable Secure Boot - May prevent proper container startup
• 64-bit support must be enabled
• Location: "Boot" → "Boot Mode" or "UEFI Settings"

Power Management Settings

• Enable "Auto Power On" or set "AC Recovery" → "Power On"
• Disable PCIe ASPM (Active State Power Management)
• Location: "Power" → "AC Recovery" and "Advanced" → "PCIe Configuration"

Hardware Features

Enable all available CPU virtualization features:

• Intel VT-x, VT-d extensions
• AMD SVM, IOMMU extensions
• Hardware virtualization support

Quick BIOS Checklist:

☑️ Virtualization Technology: ENABLED
☑️ VT-d/AMD IOMMU: ENABLED  
☑️ UEFI Boot: ENABLED
☑️ Secure Boot: DISABLED
☑️ Auto Power On: ENABLED
☑️ PCIe ASPM: DISABLED

⚠️ Important: BIOS menu names vary by manufacturer (ASUS, MSI, HP, etc.). Look for similar terms if exact names don't match.

System Requirements

• Ansible >= 2.12
• Target system: Debian 12+ (bookworm) or Ubuntu 22.04+ (jammy)
• Root/sudo access on target system
• Internet connectivity for package downloads
• Minimum 4GB RAM recommended
• 32GB+ storage space

Role Variables

Installation Control

homeassistant_install_supervisor: true    # Install Home Assistant Supervised
homeassistant_configure_network: true     # Configure networking (NetworkManager)
homeassistant_install_docker: true        # Install Docker CE
homeassistant_install_os_agent: true      # Install Home Assistant OS-Agent

Home Assistant Configuration

homeassistant_machine_type: qemux86-64    # Machine type for HA installation
homeassistant_data_share: /usr/share/hassio  # Data directory location

Supported Machine Types:

• qemux86-64 - Generic x86-64 (recommended for most systems)
• qemuarm-64 - Generic ARM64
• generic-x86-64 - Generic x86-64 alternative

OS-Agent Settings

homeassistant_os_agent_version: latest     # Use 'latest' or specific version
homeassistant_os_agent_arch: amd64         # Auto-detected based on system

Docker Configuration

homeassistant_docker_install_method: convenience_script  # Installation method

Installation Methods:

• convenience_script - Use Docker's get.docker.com script (default)
• apt_repository - Use official Docker APT repository

Network Management

homeassistant_manage_networking: true      # Enable network configuration
homeassistant_disable_ifupdown: true       # Disable traditional networking
homeassistant_enable_systemd_resolved: true # Enable systemd-resolved

Validation & Cleanup

homeassistant_validate_installation: true  # Run post-install validation
homeassistant_cleanup_downloads: true      # Remove downloaded packages
homeassistant_service_start_timeout: 300   # Service startup timeout (seconds)

Dependencies

The role automatically installs these system packages:

• network-manager - Network management
• systemd-resolved - DNS resolution
• curl - HTTP client for downloads
• lsb-release - Distribution information
• udisks2 - Disk management
• apparmor - Security profiles
• jq - JSON processing
• wget - File downloads
• ca-certificates - SSL certificates
• gnupg - Package signing

Example Playbooks

Basic Installation

---
- hosts: homeassistant_servers
  become: true
  roles:
    - role: homeassistant

Custom Configuration

---
- hosts: homeassistant_servers
  become: true
  roles:
    - role: homeassistant
      vars:
        homeassistant_machine_type: generic-x86-64
        homeassistant_os_agent_version: "1.6.0"
        homeassistant_docker_install_method: apt_repository
        homeassistant_data_share: /opt/homeassistant

Minimal Installation (Skip networking changes)

---
- hosts: homeassistant_servers
  become: true
  roles:
    - role: homeassistant
      vars:
        homeassistant_configure_network: false
        homeassistant_manage_networking: false

Tags

Use tags to run specific parts of the installation:

# Install only prerequisites
ansible-playbook -t homeassistant,prerequisites site.yml

# Configure networking only
ansible-playbook -t homeassistant,network site.yml

# Install Docker only
ansible-playbook -t homeassistant,docker site.yml

# Install OS-Agent only
ansible-playbook -t homeassistant,os-agent site.yml

# Install Supervisor only
ansible-playbook -t homeassistant,supervisor site.yml

# Run validation only
ansible-playbook -t homeassistant,validation site.yml

Post-Installation

After successful installation:

1. Access Home Assistant: http://your-server-ip:8123
2. Initial setup takes 10-20 minutes for container downloads
3. Monitor progress: journalctl -u hassio-supervisor -f
4. Check service status: systemctl status hassio-supervisor

Useful Commands

# Check all Home Assistant related services
systemctl status hassio-supervisor docker NetworkManager os-agent

# View Home Assistant logs
journalctl -u hassio-supervisor -f

# Check OS-Agent D-Bus interface
busctl introspect io.hass.os /io/hass/os

# Verify Docker containers
docker ps

# Check Home Assistant CLI
ha help

Troubleshooting

Common Issues

Web interface not accessible:

• Wait 10-20 minutes for initial container downloads
• Check firewall: ufw allow 8123/tcp
• Verify service: systemctl status hassio-supervisor

Networking issues after installation:

• Reboot the system to ensure all network changes take effect
• Check NetworkManager: systemctl status NetworkManager
• Verify DNS resolution: systemd-resolve --status

OS-Agent D-Bus errors:

• Restart OS-Agent: systemctl restart os-agent
• Check D-Bus: busctl list | grep hass

Docker permission issues:

• Add user to docker group: usermod -aG docker $USER
• Re-login or restart session

Log Locations

• Home Assistant Supervisor: journalctl -u hassio-supervisor
• OS-Agent: journalctl -u os-agent
• Docker: journalctl -u docker
• NetworkManager: journalctl -u NetworkManager

Architecture Support

Architecture	Machine Type	OS-Agent Binary	Supported
x86_64 (Intel/AMD)	qemux86-64	amd64	âœ
ARM64 (64-bit ARM)	qemuarm-64	arm64	âœ
ARM32 (32-bit ARM)	-	arm	❌ (Not recommended)

Security Considerations

• Role requires root/sudo access for system modifications
• Downloads packages from official sources only
• Validates package integrity where possible
• Configures proper file permissions and ownership
• Uses systemd service isolation
• Enables AppArmor profiles when available

License

MIT

Contributing

1. Test on clean Debian 12+ system
2. Ensure all validation steps pass
3. Update documentation for any new variables
4. Test with both installation methods (convenience_script and apt_repository)
5. Verify compatibility with different machine types