homeassistant

8 KB•MD
DirectoryView in Forgejo
README.md
8 KB • 274 lines • markdown
1# Home Assistant Supervised Role
2
3This Ansible role installs Home Assistant Supervised on Debian 12+ systems with all required dependencies, networking configuration, and proper validation.
4
5## Features
6
7- ✅ Complete networking setup (NetworkManager + systemd-resolved)
8- ✅ Docker CE installation via official methods
9- ✅ OS-Agent installation with version selection
10- ✅ Home Assistant Supervised installation with machine type configuration
11- ✅ Comprehensive validation and error checking
12- ✅ Service management and automatic startup
13- ✅ Support for multiple architectures (x86_64, arm64)
14- ✅ Cleanup of downloaded packages
15- ✅ Proper privilege escalation and security
16
17## Requirements
18
19### BIOS Configuration Requirements
20
21**Critical BIOS settings must be configured before installation:**
22
23#### Essential Virtualization Settings
24- **Enable VT-x** (Intel) or **AMD-V** (AMD) - Required for container virtualization
25- **Enable VT-d** (Intel) or **AMD IOMMU** (AMD) - Required for hardware passthrough
26- **Location**: Usually under "Advanced" → "CPU Configuration" or "Virtualization"
27
28#### Boot Mode Configuration
29- **Enable UEFI boot mode** - Modern container systems require UEFI
30- **Disable Secure Boot** - May prevent proper container startup
31- **64-bit support** must be enabled
32- **Location**: "Boot" → "Boot Mode" or "UEFI Settings"
33
34#### Power Management Settings
35- **Enable "Auto Power On"** or set "AC Recovery" → "Power On"
36- **Disable PCIe ASPM** (Active State Power Management)
37- **Location**: "Power" → "AC Recovery" and "Advanced" → "PCIe Configuration"
38
39#### Hardware Features
40Enable all available CPU virtualization features:
41- Intel VT-x, VT-d extensions
42- AMD SVM, IOMMU extensions
43- Hardware virtualization support
44
45#### Quick BIOS Checklist:
46```
47☑️ Virtualization Technology: ENABLED
48☑️ VT-d/AMD IOMMU: ENABLED  
49☑️ UEFI Boot: ENABLED
50☑️ Secure Boot: DISABLED
51☑️ Auto Power On: ENABLED
52☑️ PCIe ASPM: DISABLED
53```
54
55⚠️ **Important**: BIOS menu names vary by manufacturer (ASUS, MSI, HP, etc.). Look for similar terms if exact names don't match.
56
57### System Requirements
58- Ansible >= 2.12
59- Target system: Debian 12+ (bookworm) or Ubuntu 22.04+ (jammy)
60- Root/sudo access on target system
61- Internet connectivity for package downloads
62- Minimum 4GB RAM recommended
63- 32GB+ storage space
64
65## Role Variables
66
67### Installation Control
68```yaml
69homeassistant_install_supervisor: true    # Install Home Assistant Supervised
70homeassistant_configure_network: true     # Configure networking (NetworkManager)
71homeassistant_install_docker: true        # Install Docker CE
72homeassistant_install_os_agent: true      # Install Home Assistant OS-Agent
73```
74
75### Home Assistant Configuration
76```yaml
77homeassistant_machine_type: qemux86-64    # Machine type for HA installation
78homeassistant_data_share: /usr/share/hassio  # Data directory location
79```
80
81**Supported Machine Types:**
82- `qemux86-64` - Generic x86-64 (recommended for most systems)
83- `qemuarm-64` - Generic ARM64
84- `generic-x86-64` - Generic x86-64 alternative
85
86### OS-Agent Settings
87```yaml
88homeassistant_os_agent_version: latest     # Use 'latest' or specific version
89homeassistant_os_agent_arch: amd64         # Auto-detected based on system
90```
91
92### Docker Configuration
93```yaml
94homeassistant_docker_install_method: convenience_script  # Installation method
95```
96
97**Installation Methods:**
98- `convenience_script` - Use Docker's get.docker.com script (default)
99- `apt_repository` - Use official Docker APT repository
100
101### Network Management
102```yaml
103homeassistant_manage_networking: true      # Enable network configuration
104homeassistant_disable_ifupdown: true       # Disable traditional networking
105homeassistant_enable_systemd_resolved: true # Enable systemd-resolved
106```
107
108### Validation & Cleanup
109```yaml
110homeassistant_validate_installation: true  # Run post-install validation
111homeassistant_cleanup_downloads: true      # Remove downloaded packages
112homeassistant_service_start_timeout: 300   # Service startup timeout (seconds)
113```
114
115## Dependencies
116
117The role automatically installs these system packages:
118- `network-manager` - Network management
119- `systemd-resolved` - DNS resolution
120- `curl` - HTTP client for downloads
121- `lsb-release` - Distribution information
122- `udisks2` - Disk management
123- `apparmor` - Security profiles
124- `jq` - JSON processing
125- `wget` - File downloads
126- `ca-certificates` - SSL certificates
127- `gnupg` - Package signing
128
129## Example Playbooks
130
131### Basic Installation
132```yaml
133---
134- hosts: homeassistant_servers
135  become: true
136  roles:
137    - role: homeassistant
138```
139
140### Custom Configuration
141```yaml
142---
143- hosts: homeassistant_servers
144  become: true
145  roles:
146    - role: homeassistant
147      vars:
148        homeassistant_machine_type: generic-x86-64
149        homeassistant_os_agent_version: "1.6.0"
150        homeassistant_docker_install_method: apt_repository
151        homeassistant_data_share: /opt/homeassistant
152```
153
154### Minimal Installation (Skip networking changes)
155```yaml
156---
157- hosts: homeassistant_servers
158  become: true
159  roles:
160    - role: homeassistant
161      vars:
162        homeassistant_configure_network: false
163        homeassistant_manage_networking: false
164```
165
166## Tags
167
168Use tags to run specific parts of the installation:
169
170```bash
171# Install only prerequisites
172ansible-playbook -t homeassistant,prerequisites site.yml
173
174# Configure networking only
175ansible-playbook -t homeassistant,network site.yml
176
177# Install Docker only
178ansible-playbook -t homeassistant,docker site.yml
179
180# Install OS-Agent only
181ansible-playbook -t homeassistant,os-agent site.yml
182
183# Install Supervisor only
184ansible-playbook -t homeassistant,supervisor site.yml
185
186# Run validation only
187ansible-playbook -t homeassistant,validation site.yml
188```
189
190## Post-Installation
191
192After successful installation:
193
1941. **Access Home Assistant**: `http://your-server-ip:8123`
1952. **Initial setup takes 10-20 minutes** for container downloads
1963. **Monitor progress**: `journalctl -u hassio-supervisor -f`
1974. **Check service status**: `systemctl status hassio-supervisor`
198
199### Useful Commands
200
201```bash
202# Check all Home Assistant related services
203systemctl status hassio-supervisor docker NetworkManager os-agent
204
205# View Home Assistant logs
206journalctl -u hassio-supervisor -f
207
208# Check OS-Agent D-Bus interface
209busctl introspect io.hass.os /io/hass/os
210
211# Verify Docker containers
212docker ps
213
214# Check Home Assistant CLI
215ha help
216```
217
218## Troubleshooting
219
220### Common Issues
221
222**Web interface not accessible:**
223- Wait 10-20 minutes for initial container downloads
224- Check firewall: `ufw allow 8123/tcp`
225- Verify service: `systemctl status hassio-supervisor`
226
227**Networking issues after installation:**
228- Reboot the system to ensure all network changes take effect
229- Check NetworkManager: `systemctl status NetworkManager`
230- Verify DNS resolution: `systemd-resolve --status`
231
232**OS-Agent D-Bus errors:**
233- Restart OS-Agent: `systemctl restart os-agent`
234- Check D-Bus: `busctl list | grep hass`
235
236**Docker permission issues:**
237- Add user to docker group: `usermod -aG docker $USER`
238- Re-login or restart session
239
240### Log Locations
241
242- **Home Assistant Supervisor**: `journalctl -u hassio-supervisor`
243- **OS-Agent**: `journalctl -u os-agent`
244- **Docker**: `journalctl -u docker`
245- **NetworkManager**: `journalctl -u NetworkManager`
246
247## Architecture Support
248
249| Architecture | Machine Type | OS-Agent Binary | Supported |
250|--------------|--------------|-----------------|-----------|
251| x86_64 (Intel/AMD) | qemux86-64 | amd64 | ✅ |
252| ARM64 (64-bit ARM) | qemuarm-64 | arm64 | ✅ |
253| ARM32 (32-bit ARM) | - | arm | ❌ (Not recommended) |
254
255## Security Considerations
256
257- Role requires root/sudo access for system modifications
258- Downloads packages from official sources only
259- Validates package integrity where possible
260- Configures proper file permissions and ownership
261- Uses systemd service isolation
262- Enables AppArmor profiles when available
263
264## License
265
266MIT
267
268## Contributing
269
2701. Test on clean Debian 12+ system
2712. Ensure all validation steps pass
2723. Update documentation for any new variables
2734. Test with both installation methods (convenience_script and apt_repository)
2745. Verify compatibility with different machine types