vault-para/100-project/Personal/Software/Home Assistant/Install.md

---

Table of Contents

1. Prerequisites
2. Prepare Your Debian System
3. Install Docker
4. Configure Docker Daemon (Optional: HTTP Proxy)
5. Install Home Assistant Supervised
6. Post-Installation Configuration
7. Configure Home Assistant
8. Maintenance and Best Practices
9. Troubleshooting
10. Additional Resources

---

1. Prerequisites

Before you begin, ensure that you have the following:

• Hardware:

  • A device running Debian (Raspberry Pi 4 recommended for ARM architecture or an x86_64-based server for better performance).
  • Reliable storage (SSD recommended over HDD or SD cards for durability and speed).
  • Stable internet connection.

• Software:

  • Debian: Ensure you have a fresh installation of Debian 11 (Bullseye) or later.
  • Access: Root or sudo privileges on the Debian system.

• Tools:

  • Terminal Access: SSH access or direct access to the Debian machine's terminal.
  • Internet Connection: Required for downloading packages and Docker images.

---

2. Prepare Your Debian System

2.1 Install Debian

If you haven't already installed Debian, follow these steps:

1. Download Debian ISO:

   • Visit the official Debian website and download the latest stable release (preferably Debian 11 "Bullseye").

2. Create Installation Media:

   • Use tools like Rufus (Windows) or dd command (Linux/macOS) to create a bootable USB drive.

3. Install Debian:

   • Boot from the USB drive and follow the on-screen instructions.
   • Choose a Minimal Installation to reduce unnecessary packages.
   • Set up a strong root password and create a user with sudo privileges.

2.2 Update the System

Once Debian is installed, update the package lists and upgrade existing packages:

sudo apt update && sudo apt upgrade -y

2.3 Set Hostname and Timezone

1. Set Hostname:

   Replace homeassistant with your desired hostname.

   sudo hostnamectl set-hostname homeassistant
   

2. Set Timezone:

   sudo dpkg-reconfigure tzdata
   

   Follow the prompts to select your timezone.

2.4 Install Essential Packages

Install necessary packages required for Home Assistant Supervised:

sudo apt install -y jq curl avahi-daemon dbus network-manager apparmor-utils

---

3. Install Docker

Home Assistant Supervised relies on Docker to manage containers. Follow these steps to install Docker Engine.

3.1 Remove Old Docker Versions

Ensure no older versions of Docker are present:

sudo apt remove -y docker docker-engine docker.io containerd runc

3.2 Install Docker Dependencies

sudo apt install -y ca-certificates curl gnupg lsb-release

3.3 Add Docker’s Official GPG Key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

3.4 Set Up the Docker Repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3.5 Install Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.6 Verify Docker Installation

Check Docker version and status:

docker --version
sudo systemctl status docker

You should see Docker running. Press q to exit the status view.

3.7 Manage Docker as a Non-Root User (Optional)

To run Docker commands without sudo, add your user to the docker group:

sudo usermod -aG docker $USER

Log out and back in for the changes to take effect.

---

4. Configure Docker Daemon (Optional: HTTP Proxy)

If your network requires Docker to use an HTTP proxy, configure it as follows:

4.1 Create or Edit Docker Daemon Configuration

Open /etc/docker/daemon.json in a text editor:

sudo nano /etc/docker/daemon.json

4.2 Add Proxy Settings

Replace http://your-proxy:port with your actual proxy details. If you don't need a proxy, you can skip this step.

{
  "proxies": {
    "default": {
      "httpProxy": "http://your-proxy:port",
      "httpsProxy": "http://your-proxy:port",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

4.3 Save and Exit

Press CTRL + O to save and CTRL + X to exit.

4.4 Restart Docker to Apply Changes

sudo systemctl restart docker

4.5 Verify Proxy Configuration (Optional)

Run a Docker container to verify proxy settings:

docker run --rm alpine env | grep -i proxy

You should see the proxy variables if configured correctly.

---

5. Install Home Assistant Supervised

Follow these steps to install Home Assistant Supervised on your Debian system.

5.1 Download the Supervised Installer Script

curl -Lo installer.sh https://raw.githubusercontent.com/home-assistant/supervised-installer/main/installer.sh

5.2 Make the Script Executable

chmod +x installer.sh

5.3 Run the Installer Script

Run the installer with the appropriate machine type. Replace your_machine_type with your hardware. Common types include:

• raspberrypi4 for Raspberry Pi 4
• generic-x86-64 for standard 64-bit PCs

Example for Raspberry Pi 4:

sudo bash installer.sh --machine raspberrypi4

Example for Generic x86_64:

sudo bash installer.sh --machine generic-x86-64

5.4 Follow On-Screen Prompts

The installer will guide you through the process, including:

• Confirming installation parameters.
• Installing necessary Docker containers (Supervisor, Home Assistant Core, etc.).

Note: Ensure your network is stable during the installation to allow the script to download required Docker images.

5.5 Verify Installation

After the installation completes, check the status of Home Assistant Supervisor:

sudo systemctl status hassio-supervisor.service

You should see that the Supervisor is active and running.

---

6. Post-Installation Configuration

6.1 Access Home Assistant Web Interface

1. Find Your Server's IP Address:

   hostname -I
   

   Note down the IP address (e.g., 192.168.1.100).

2. Open Web Browser:

   Navigate to http://<your-server-ip>:8123 (e.g., http://192.168.1.100:8123).

3. Initial Setup:

   • Create an Account: Follow the prompts to create your Home Assistant user account.
   • Configure Location: Set your location, unit system, and time zone.
   • Set Up Home: Follow the guided setup to add devices and integrations.

6.2 Configure Supervisor Settings

1. Navigate to Supervisor Panel:

   • Click on Supervisor in the left sidebar.

2. Update Supervisor and Core:

   • If prompted, update the Supervisor and Home Assistant Core to the latest versions.

3. Install Add-ons:

   • Click on Add-on Store.
   • Browse and install desired add-ons (e.g., File Editor, Samba Share, Mosquitto MQTT Broker).
   • Configure each add-on as needed.

---

7. Configure Home Assistant

After installation, you can customize and extend Home Assistant to suit your needs.

7.1 Basic Configuration

1. Integrations:

   • Automatic Discovery: Home Assistant can automatically discover devices on your network.
   • Manual Integration: Go to Settings > Devices & Services > Add Integration to add integrations manually.

2. Dashboard Customization:

   • Edit Dashboard: Click on the three dots in the top-right corner of the dashboard and select Edit Dashboard.
   • Add Cards: Use various card types (e.g., entities, glance, gauge) to display information.
   • Organize Views: Create multiple views for different areas or functionalities in your home.

7.2 Adding Users and Permissions

1. User Management:

   • Go to Settings > System > Users.
   • Add new users, assign roles (Administrator or User), and manage permissions.

7.3 Automations and Scripts

1. Create Automations:

   • Navigate to Settings > Automations & Scenes > Automations.
   • Use the Editor to create triggers, conditions, and actions.
   • Example: Turn on lights when motion is detected.

2. Create Scripts:

   • Navigate to Settings > Automations & Scenes > Scripts.
   • Define sequences of actions that can be triggered manually or via automations.

7.4 Adding Custom Components

1. File Editor Add-on:

   • Install the File Editor add-on from the Add-on Store.
   • Use it to edit configuration.yaml and other YAML files directly within Home Assistant.

2. Restart Home Assistant:

   • After making changes to YAML files, restart Home Assistant to apply them.
   • Navigate to Settings > System > Restart.

7.5 Setting Up Backups (Snapshots)

1. Create Snapshots:

   • Go to Supervisor > Snapshots.
   • Click Create Snapshot to back up your configuration and add-ons.

2. Automate Backups:

   • Use add-ons like Google Drive Backup or Samba Share to store snapshots externally.
   • Schedule regular backups to ensure data safety.

---

8. Maintenance and Best Practices

8.1 Regular Updates

• Home Assistant Core and Supervisor:
  • Regularly update to the latest versions via the Supervisor interface.
• Add-ons:
  • Keep add-ons up to date to benefit from new features and security patches.

8.2 Backup Strategy

• Local Backups:
  • Utilize Home Assistant's snapshot feature.
• Remote Backups:
  • Store backups on external drives or cloud services using add-ons.

8.3 Security Measures

• Secure Access:

  • Enable SSL/TLS for secure remote access.
  • Use strong passwords and enable two-factor authentication (2FA).

• Firewall Configuration:

  • Limit access to Home Assistant ports to trusted networks.

• Regular Monitoring:

  • Keep an eye on logs and system performance to detect any anomalies.

8.4 Resource Monitoring

• Supervisor > System:

  • Monitor CPU, memory, and disk usage to ensure optimal performance.

• Add-ons:

  • Some add-ons provide their own monitoring tools (e.g., System Monitor).

---

9. Troubleshooting

9.1 Common Issues

1. Supervisor Not Starting:

   • Check Docker Status:

     sudo systemctl status docker
     

   • Restart Docker:

     sudo systemctl restart docker
     

   • Check Logs:

     sudo journalctl -u docker -f
     sudo journalctl -u hassio-supervisor.service -f
     

2. Add-ons Not Installing:

   • Verify Network Connectivity: Ensure your server can access the internet.
   • Check Docker Permissions: Ensure the user running Docker has the necessary permissions.
   • Review Logs: Navigate to Supervisor > System > Logs for detailed error messages.

3. Home Assistant Not Accessible:

   • Check Container Status:

     docker ps
     

     Ensure the homeassistant container is running.

   • Verify Port Accessibility: Ensure port 8123 is open and not blocked by a firewall.

9.2 Getting Help

• Home Assistant Community Forums: Home Assistant Community
• Home Assistant Discord Server: Join Discord
• Official Documentation: Home Assistant Docs

---

10. Additional Resources

• Home Assistant Supervised Installer Repository:

  • GitHub - home-assistant/supervised-installer

• Official Home Assistant Installation Guides:

  • Home Assistant Installation Overview

• Docker Documentation:

  • Docker Engine Overview

• Home Assistant Add-ons Documentation:

  • Home Assistant Add-ons

---

Summary

By following the steps outlined above, you can successfully install Home Assistant Supervised on a Debian Linux server, enabling you to manage Home Assistant and its add-ons via Docker containers effectively. This setup provides a balance between ease of use and the flexibility to customize your Home Assistant environment to meet your specific needs.

Key Points:

• Home Assistant Supervised combines the power of the Supervisor with the flexibility of a standard Linux environment.
• Docker is central to managing Home Assistant Core and its add-ons.
• Regular Maintenance, including updates and backups, is crucial for a stable and secure Home Assistant setup.
• Community Resources are invaluable for troubleshooting and optimizing your Home Assistant experience.

Feel free to reach out to the Home Assistant community if you encounter any challenges or have specific questions during your setup!