/
/
/
This repo is destined for my server automations and setup.
1---
2# ============================================================================
3# Home Assistant Supervised Complete Installation Playbook
4# ============================================================================
5#
6# This playbook sets up a complete Home Assistant Supervised installation
7# on Debian 12 with proper user management, security hardening, and Docker.
8# All configuration is managed via group_vars/homeassistant.yml
9#
10# QUICK START:
11#
12# 1. Set up your inventory:
13# - Edit inventory/hosts
14# - Add your server to the [homeassistant] group
15# - Example: homeassistant-server ansible_host=192.168.1.100
16#
17# 2. Customize settings (optional):
18# - Edit group_vars/homeassistant.yml
19# - Set homeassistant_ssh_key for secure access
20# - Adjust system_timezone if needed
21#
22# 3. Run the playbook:
23# ansible-playbook -i inventory/hosts homeassistant.yml
24#
25# USAGE EXAMPLES:
26#
27# Deploy to all homeassistant servers:
28# ansible-playbook -i inventory/hosts homeassistant.yml
29#
30# Deploy to specific server:
31# ansible-playbook -i inventory/hosts homeassistant.yml -l homeassistant-server
32#
33# Run specific components (using tags):
34# ansible-playbook -i inventory/hosts homeassistant.yml --tags "user,system"
35# ansible-playbook -i inventory/hosts homeassistant.yml --tags "security"
36# ansible-playbook -i inventory/hosts homeassistant.yml --tags "homeassistant"
37#
38# Skip components (useful for updates):
39# ansible-playbook -i inventory/hosts homeassistant.yml --skip-tags "user"
40#
41# Test run (dry run):
42# ansible-playbook -i inventory/hosts homeassistant.yml --check
43#
44# PREREQUISITES:
45# - Fresh Debian 11 or 12 installation
46# - SSH access with sudo privileges for ansible_user
47# - Internet connectivity for package downloads
48# - At least 2GB RAM and 32GB storage
49# - Static IP address recommended
50# - Server added to [homeassistant] group in inventory/hosts
51#
52# ============================================================================
53
54- name: "Complete Home Assistant Supervised Setup"
55 hosts: homeassistant_servers
56 become: true
57 gather_facts: true
58
59 # All configuration is managed via group_vars/homeassistant.yml
60 # This keeps the playbook clean and allows per-group customization
61
62 pre_tasks:
63 - name: Display deployment information
64 debug:
65 msg: |
66 ============================================================================
67 Home Assistant Supervised Installation Starting
68 ============================================================================
69 Target Host: {{ inventory_hostname }}
70 Target IP: {{ ansible_default_ipv4.address }}
71 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
72 Architecture: {{ ansible_architecture }}
73 User: {{ homeassistant_user }}
74 ============================================================================
75 tags: always
76
77 - name: Validate system requirements
78 assert:
79 that:
80 - ansible_distribution == "Debian"
81 - ansible_distribution_major_version | int >= 11
82 - ansible_memtotal_mb >= 1500 # Minimum 1.5GB RAM
83 - ansible_processor_vcpus >= 2 # Minimum 2 CPU cores
84 fail_msg: |
85 System requirements not met:
86 - Requires Debian 11 or 12
87 - Minimum 1.5GB RAM (found {{ ansible_memtotal_mb }}MB)
88 - Minimum 2 CPU cores (found {{ ansible_processor_vcpus }})
89 success_msg: "System requirements validated successfully"
90 tags: always
91
92 - name: Verify server is in homeassistant_servers group
93 fail:
94 msg: "This server must be in the [homeassistant_servers] inventory group. Check your inventory/hosts file."
95 when: "'homeassistant_servers' not in group_names"
96 tags: always
97
98 # ============================================================================
99 # ROLE EXECUTION ORDER (CRITICAL FOR PROPER INSTALLATION)
100 # ============================================================================
101
102 roles:
103 # 1. USER MANAGEMENT - Create homeassistant user with proper groups
104 - role: user
105 tags: [user, setup]
106
107 # 2. SYSTEM SETUP - Basic system configuration and packages
108 - role: system
109 tags: [system, setup]
110
111 # 3. DOCKER INSTALLATION - Install Docker using geerlingguy.docker
112 - role: geerlingguy.docker
113 tags: [docker, setup]
114
115 # 4. SECURITY HARDENING - Apply security settings
116 - role: geerlingguy.security
117 tags: [security, hardening]
118
119 # 5. HOME ASSISTANT SUPERVISED - Complete installation (Docker required)
120 - role: homeassistant
121 tags: [homeassistant, ha]
122
123 # ============================================================================
124 # POST-INSTALLATION TASKS
125 # ============================================================================
126
127 post_tasks:
128 - name: Check if network transition is pending
129 stat:
130 path: /etc/systemd/system/ha-network-transition.service
131 register: network_transition_pending
132
133 - name: Display network transition requirement
134 debug:
135 msg: |
136 â ï¸ NETWORK TRANSITION PENDING â ï¸
137
138 A reboot is required to complete the NetworkManager transition.
139 The transition script is ready at: /usr/local/bin/ha-network-transition.sh
140
141 After Home Assistant installation completes:
142 1. Reboot the server: sudo reboot
143 2. Check transition log: cat /var/log/ha-network-transition.log
144 3. Verify NetworkManager: systemctl status NetworkManager
145 when: network_transition_pending.stat.exists
146
147 - name: Wait for Home Assistant to become available
148 uri:
149 url: "http://{{ ansible_default_ipv4.address }}:8123"
150 method: GET
151 status_code: 200
152 timeout: 10
153 register: ha_check
154 until: ha_check.status == 200
155 retries: 30
156 delay: 10
157 ignore_errors: yes
158 tags: [homeassistant, validation]
159
160 - name: Display installation summary
161 debug:
162 msg: |
163 ============================================================================
164 Home Assistant Supervised Installation Complete!
165 ============================================================================
166
167 ð Home Assistant Access:
168 Web Interface: http://{{ ansible_default_ipv4.address }}:8123
169 SSH Access: ssh {{ homeassistant_user }}@{{ ansible_default_ipv4.address }}
170
171 ð System Information:
172 Host: {{ inventory_hostname }}
173 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
174 Architecture: {{ homeassistant_machine_type }}
175 User: {{ homeassistant_user }}
176 Docker Version: {{ docker_version.stdout | default('Unknown') }}
177
178 ð§ Services Status:
179 - Home Assistant Supervisor: {{ 'Running' if ha_check.status == 200 else 'Starting (may take 5-10 minutes)' }}
180 - Docker: Running
181 - OS Agent: Installed
182 - NetworkManager: Configured
183
184 ð Next Steps:
185 1. Open http://{{ ansible_default_ipv4.address }}:8123 in your browser
186 2. Complete Home Assistant onboarding process
187 3. Install HACS (Home Assistant Community Store)
188 4. Configure integrations and add-ons
189 5. Set up backups and monitoring
190
191 ð¡ Useful Commands:
192 - Check supervisor status: sudo systemctl status hassio-supervisor
193 - View supervisor logs: sudo journalctl -fu hassio-supervisor
194 - Restart supervisor: sudo systemctl restart hassio-supervisor
195 - Docker containers: docker ps
196
197 â ï¸ Important Notes:
198 - Initial startup may take 5-10 minutes
199 - Create backups before major updates
200 - Monitor system resources (RAM usage can grow over time)
201 - Use SSH access for system maintenance
202
203 ============================================================================
204 tags: always
205
206 - name: Save installation details to file
207 copy:
208 content: |
209 Home Assistant Supervised Installation Details
210 =============================================
211
212 Installation Date: {{ ansible_date_time.iso8601 }}
213 Host: {{ inventory_hostname }}
214 IP Address: {{ ansible_default_ipv4.address }}
215 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
216 Architecture: {{ ansible_architecture }}
217 Machine Type: {{ homeassistant_machine_type }}
218
219 User Configuration:
220 - Username: {{ homeassistant_user }}
221 - Groups: {{ homeassistant_user_groups | join(', ') }}
222 - Sudo Access: Passwordless
223
224 Home Assistant:
225 - Web Interface: http://{{ ansible_default_ipv4.address }}:8123
226 - Data Directory: {{ homeassistant_data_share | default('/usr/share/hassio') }}
227 - Supervisor Status: {{ 'Running' if ha_check.status == 200 else 'Starting' }}
228
229 Docker Configuration:
230 - Compose Installed: {{ docker_install_compose }}
231 - Users with Access: {{ docker_users | join(', ') }}
232 - Log Rotation: 50MB max, 3 files
233
234 Security:
235 - SSH Port: {{ security_ssh_port }}
236 - Root Login: Disabled
237 - Password Authentication: Disabled
238 - Fail2ban: {{ security_fail2ban_enabled | default('Enabled') }}
239 - Auto Updates: {{ security_autoupdate_enabled }}
240
241 Useful Commands:
242 - Check HA status: sudo systemctl status hassio-supervisor
243 - View HA logs: sudo journalctl -fu hassio-supervisor
244 - Docker containers: docker ps
245 - System resources: htop
246
247 dest: "/home/{{ homeassistant_user }}/homeassistant-installation-details.txt"
248 owner: "{{ homeassistant_user }}"
249 group: "{{ homeassistant_user }}"
250 mode: "0644"
251 tags: [homeassistant, documentation]
252
253# ============================================================================
254# TROUBLESHOOTING AND MAINTENANCE
255# ============================================================================
256#
257# Common Issues and Solutions:
258#
259# 1. Home Assistant not accessible after installation:
260# - Wait 5-10 minutes for initial container downloads
261# - Check: sudo systemctl status hassio-supervisor
262# - Check: docker ps
263# - Check logs: sudo journalctl -fu hassio-supervisor
264#
265# 2. Permission issues with Docker:
266# - Ensure user is in docker group: groups {{ homeassistant_user }}
267# - Re-run user role: ansible-playbook homeassistant.yml --tags user
268# - Log out and back in to refresh group membership
269#
270# 3. Network issues:
271# - Check NetworkManager status: systemctl status NetworkManager
272# - Verify interfaces: ip addr show
273# - Check routes: ip route show
274#
275# 4. Storage issues:
276# - Check disk usage: df -h
277# - Clean Docker: docker system prune -a
278# - Check HA data: du -sh /usr/share/hassio/*
279#
280# 5. Update issues:
281# - Always backup before updates
282# - Check system updates: apt list --upgradable
283# - Update supervisor: docker pull homeassistant/amd64-hassio-supervisor:latest
284#
285# Maintenance Tasks:
286# - Weekly: Check logs, monitor resources, review updates
287# - Monthly: Clean old Docker images, check backups
288# - Before updates: Create full system backup
289# - After changes: Test all critical automations
290#
291# ============================================================================