/
/
/
This repo is destined for my server automations and setup.
1---
2# ============================================================================
3# Home Assistant Supervised Complete Installation Playbook
4# ============================================================================
5#
6#
7# PREREQUISITES:
8# - Fresh Debian 11 or 12 installation
9# - SSH access with sudo privileges for ansible_user
10# - Internet connectivity for package downloads
11# - Static IP address recommended
12#
13# ============================================================================
14
15- name: "Complete Home Assistant Supervised Setup"
16 hosts: homeassistant_servers
17 become: true
18 gather_facts: true
19
20 pre_tasks:
21 - name: Verify homeassistant server requirements
22 assert:
23 that:
24 - ansible_distribution == "Debian"
25 - ansible_distribution_major_version | int >= 11
26 - ansible_memtotal_mb >= 1500 # Minimum 1.5GB RAM
27 - ansible_processor_vcpus >= 2 # Minimum 2 CPU cores
28 fail_msg: |
29 Home Assistant system requirements not met:
30 - Requires Debian 11 or 12
31 - Minimum 1.5GB RAM (found {{ ansible_memtotal_mb }}MB)
32 - Minimum 2 CPU cores (found {{ ansible_processor_vcpus }})
33 success_msg: "Home Assistant system requirements validated successfully"
34 tags: always
35
36 - name: Verify server is in homeassistant_servers group
37 fail:
38 msg: "This server must be in the [homeassistant_servers] inventory group. Check your inventory/hosts file."
39 when: "'homeassistant_servers' not in group_names"
40 tags: always
41
42 - name: Display homeassistant deployment information
43 debug:
44 msg: |
45 ============================================================================
46 Home Assistant Supervised Installation Starting
47 ============================================================================
48 Target Host: {{ inventory_hostname }}
49 Target IP: {{ ansible_default_ipv4.address }}
50 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
51 Architecture: {{ ansible_architecture }}
52 User: {{ my_user_username }}
53 Machine Type: {{ homeassistant_machine_type }}
54 ============================================================================
55 tags: always
56
57 # ============================================================================
58 # ROLE EXECUTION ORDER (CRITICAL FOR PROPER INSTALLATION)
59 # ============================================================================
60
61 roles:
62 # 1. USER MANAGEMENT - Create homeassistant user with proper groups
63 - role: user
64 tags: [user, setup]
65
66 # 2. SYSTEM SETUP - Basic system configuration and packages
67 - role: system
68 tags: [system, setup]
69
70 # 3. DOCKER INSTALLATION - Install Docker using geerlingguy.docker
71 - role: geerlingguy.docker
72 tags: [docker, setup]
73
74 # 4. DOCKER FRAMEWORK - Setup Docker directory structure
75 - role: docker-framework
76 tags: [docker, framework]
77
78 # 5. SECURITY HARDENING - Apply security settings
79 - role: geerlingguy.security
80 tags: [security, hardening]
81
82 # 5. HOME ASSISTANT SUPERVISED - Complete installation (Docker required)
83 - role: homeassistant
84 tags: [homeassistant, ha]
85
86 # ============================================================================
87 # POST-INSTALLATION TASKS
88 # ============================================================================
89
90 post_tasks:
91 - name: Check if network transition is pending
92 stat:
93 path: /etc/systemd/system/ha-network-transition.service
94 register: network_transition_pending
95
96 - name: Display network transition requirement
97 debug:
98 msg: |
99 â ï¸ NETWORK TRANSITION PENDING â ï¸
100
101 A reboot is required to complete the NetworkManager transition.
102 The transition script is ready at: /usr/local/bin/ha-network-transition.sh
103
104 After Home Assistant installation completes:
105 1. Reboot the server: sudo reboot
106 2. Check transition log: cat /var/log/ha-network-transition.log
107 3. Verify NetworkManager: systemctl status NetworkManager
108 when: network_transition_pending.stat.exists
109
110 - name: Verify core services are running
111 systemd:
112 name: "{{ item }}"
113 state: started
114 enabled: yes
115 loop:
116 - docker
117 - NetworkManager
118 tags: ['verification']
119
120 - name: Verify OS-Agent is installed and running
121 systemd:
122 name: os-agent
123 state: started
124 enabled: yes
125 register: os_agent_status
126 tags: ['verification', 'ha-validation']
127
128 - name: Verify Home Assistant Supervisor is installed
129 stat:
130 path: /usr/sbin/hassio-supervisor
131 register: supervisor_installed
132 tags: ['verification', 'ha-validation']
133
134 - name: Wait for Home Assistant to become available
135 uri:
136 url: "http://{{ ansible_default_ipv4.address }}:8123"
137 method: GET
138 status_code: 200
139 timeout: 10
140 register: ha_check
141 until: ha_check.status == 200
142 retries: 30
143 delay: 10
144 ignore_errors: yes
145 tags: [homeassistant, validation]
146
147 - name: Display installation summary
148 debug:
149 msg: |
150 ============================================================================
151 Home Assistant Supervised Installation Complete!
152 ============================================================================
153
154 ð Home Assistant Access:
155 Web Interface: http://{{ ansible_default_ipv4.address }}:8123
156 SSH Access: ssh {{ my_user_username }}@{{ ansible_default_ipv4.address }}
157
158 ð System Information:
159 Host: {{ inventory_hostname }}
160 IP Address: {{ ansible_default_ipv4.address }}
161 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
162 Architecture: {{ ansible_architecture }}
163 Machine Type: {{ homeassistant_machine_type }}
164 User: {{ my_user_username }}
165 Docker Version: {{ docker_version.stdout | default('Unknown') }}
166
167 ð§ Services Status:
168 - Home Assistant Supervisor: {{ 'Running' if ha_check.status == 200 else 'Starting (may take 5-10 minutes)' }}
169 - Docker: Running
170 - OS Agent: {{ 'Running' if os_agent_status is defined and os_agent_status.state == 'started' else 'Installed' }}
171 - NetworkManager: Configured
172 - Supervisor Installed: {{ 'Yes' if supervisor_installed.stat.exists else 'No' }}
173
174 ð Next Steps:
175 1. Open http://{{ ansible_default_ipv4.address }}:8123 in your browser
176 2. Complete Home Assistant onboarding process
177 3. Install HACS (Home Assistant Community Store)
178 4. Configure integrations and add-ons
179 5. Set up backups and monitoring
180
181 ð¡ Useful Commands:
182 - Check supervisor status: sudo systemctl status hassio-supervisor
183 - View supervisor logs: sudo journalctl -fu hassio-supervisor
184 - Restart supervisor: sudo systemctl restart hassio-supervisor
185 - Docker containers: docker ps
186 - OS Agent status: systemctl status os-agent
187
188 â ï¸ Important Notes:
189 - Initial startup may take 5-10 minutes
190 - Create backups before major updates
191 - Monitor system resources (RAM usage can grow over time)
192 - Use SSH access for system maintenance
193 {% if network_transition_pending.stat.exists %}
194 - Network transition pending - reboot required
195 {% endif %}
196
197 ============================================================================
198 tags: always
199
200 - name: Save installation details to file
201 copy:
202 content: |
203 Home Assistant Supervised Installation Details
204 =============================================
205
206 Installation Date: {{ ansible_date_time.iso8601 }}
207 Host: {{ inventory_hostname }}
208 IP Address: {{ ansible_default_ipv4.address }}
209 OS: {{ ansible_distribution }} {{ ansible_distribution_version }}
210 Architecture: {{ ansible_architecture }}
211 Machine Type: {{ homeassistant_machine_type }}
212
213 User Configuration:
214 - Username: {{ my_user_username }}
215 - Groups: {{ my_user_groups | join(', ') }}
216 - Sudo Access: Passwordless
217
218 Home Assistant:
219 - Web Interface: http://{{ ansible_default_ipv4.address }}:8123
220 - Data Directory: {{ homeassistant_data_share | default('/usr/share/hassio') }}
221 - Supervisor Status: {{ 'Running' if ha_check.status == 200 else 'Starting' }}
222 - OS Agent Status: {{ 'Running' if os_agent_status is defined and os_agent_status.state == 'started' else 'Installed' }}
223
224 Docker Configuration:
225 - Compose Installed: {{ docker_install_compose }}
226 - Users with Access: {{ docker_users | join(', ') }}
227 - Log Rotation: 50MB max, 3 files
228
229 Security:
230 - SSH Port: {{ security_ssh_port }}
231 - Root Login: Disabled
232 - Password Authentication: Disabled
233 - Fail2ban: {{ security_fail2ban_enabled | default('Enabled') }}
234 - Auto Updates: {{ security_autoupdate_enabled }}
235
236 Useful Commands:
237 - Check HA status: sudo systemctl status hassio-supervisor
238 - View HA logs: sudo journalctl -fu hassio-supervisor
239 - Docker containers: docker ps
240 - System resources: htop
241
242 dest: "/home/{{ my_user_username }}/homeassistant-installation-details.txt"
243 owner: "{{ my_user_username }}"
244 group: "{{ my_user_username }}"
245 mode: "0644"
246 tags: [homeassistant, documentation]
247