Codakey
Play
← Back to home-assistant/core

How to Deploy & Use home-assistant/core

# Home Assistant Core Deployment & Usage Guide

Complete guide for deploying and running Home Assistant Core, the open-source home automation platform that puts local control and privacy first.

## 1. Prerequisites

### System Requirements
- **Python**: 3.12 or newer (3.13 recommended)
- **Node.js**: 18.x or 20.x (required for frontend builds)
- **Git**: For cloning the repository
- **OS**: Linux recommended (Ubuntu 22.04+, Debian 12+, or Alpine Linux)
- **Memory**: Minimum 2GB RAM (4GB+ recommended)
- **Storage**: 10GB+ free space

### System Dependencies
Install required system libraries:

**Ubuntu/Debian:**
```bash
sudo apt-get install -y \
   libffi-dev \
   libssl-dev \
   libjpeg-dev \
   libturbojpeg0-dev \
   autoconf \
   build-essential \
   libopenjp2-7 \
   libtiff6 \
   libtiff5 \
   libczmq-dev \
   cmake

Alpine Linux:

apk add --no-cache \
    alpine-sdk \
    libffi-dev \
    openssl-dev \
    jpeg-dev \
    zlib-dev \
    autoconf \
    automake \
    libtool \
    cmake

Hardware Requirements (Optional)

  • Z-Wave: Z-Wave JS server (separate installation) + USB stick (e.g., Zooz ZST10-700, Aeotec Z-Stick 7)
  • Zigbee (ZHA): Compatible USB coordinator (e.g., SkyConnect, ConBee II, Sonoff ZBDongle-E)
  • Sonos: Speakers on same network subnet

2. Installation

Clone Repository

git clone https://github.com/home-assistant/core.git
cd core

Python Environment Setup

# Create virtual environment
python3.12 -m venv venv

# Activate
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

# Upgrade pip
pip install --upgrade pip setuptools wheel

Install Dependencies

# Install Home Assistant Core in editable mode
pip install -e .

# Install test dependencies (optional, for development)
pip install -r requirements_test.txt

# Install pre-commit hooks (for development)
pre-commit install

Frontend Setup (Required for UI)

# Install Node dependencies
cd homeassistant/components/frontend
npm install
cd ../../..

# Or use the setup script
script/setup

3. Configuration

Initial Configuration Directory

Create your configuration directory:

mkdir -p config
export HASS_CONFIG=$(pwd)/config

Environment Variables

# Optional: Set config path
export HASS_CONFIG=/path/to/config

# Optional: Development mode
export HASS_DEV=1

# Optional: Disable pip version check (speeds up startup)
export PIP_DISABLE_PIP_VERSION_CHECK=1

First-Time Setup

Home Assistant creates configuration.yaml automatically on first run, but you can pre-configure:

config/configuration.yaml:

homeassistant:
  name: Home
  latitude: !secret latitude
  longitude: !secret longitude
  elevation: 0
  unit_system: metric
  time_zone: UTC

# Enable default components
config:
frontend:
history:
logbook:

# Example integrations (configure via UI or YAML)
# zha:  # Zigbee Home Automation
#   device:
#     path: /dev/ttyUSB0
#     baudrate: 115200

# zwave_js:  # Requires Z-Wave JS server running separately
#   url: ws://localhost:3000

Secrets Management

Create config/secrets.yaml:

latitude: 00.0000
longitude: 00.0000

4. Build & Run

Development Mode

# Run with debug logging and auto-reload
hass -c config --debug

# Or with verbose logging
hass -c config --verbose

Production Mode

# Standard production run
hass -c config

# Run as daemon (Linux)
nohup hass -c config > hass.log 2>&1 &

Frontend Development (Hot Reload)

# Terminal 1: Start backend
hass -c config --debug

# Terminal 2: Start frontend dev server
cd homeassistant/components/frontend
npm run dev

Building Frontend for Production

script/build_frontend

Verification

Access the UI at http://localhost:8123

  • First boot takes 1-3 minutes (dependency installation)
  • Create account on first access

5. Deployment

Option A: Docker (Recommended for Production)

# Official image
docker run -d \
  --name homeassistant \
  --privileged \
  --restart unless-stopped \
  -e TZ=America/New_York \
  -v /PATH_TO_CONFIG:/config \
  -v /run/udev:/run/udev:ro \
  --network host \
  ghcr.io/home-assistant/home-assistant:stable

Docker Compose:

version: '3'
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    privileged: true
    restart: unless-stopped
    environment:
      - TZ=America/New_York
    volumes:
      - ./config:/config
      - /run/udev:/run:ro
    network_mode: host

Option B: Home Assistant OS (Easiest)

Download pre-built images for:

  • Raspberry Pi (3/4/5)
  • Intel NUC
  • VirtualBox/VMware
  • Proxmox

Flash to SD card/USB using Etcher or boot ISO.

Option C: Python Virtual Environment (Advanced)

Use the manual installation above with systemd service:

Create systemd service /etc/systemd/system/home-assistant@USER.service:

[Unit]
Description=Home Assistant
After=network-online.target

[Service]
Type=simple
User=%I
WorkingDirectory=/home/%I/.homeassistant
ExecStart=/home/%I/homeassistant/bin/hass -c /home/%I/.homeassistant
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl --system daemon-reload
sudo systemctl enable home-assistant@$USER
sudo systemctl start home-assistant@$USER

Option D: Home Assistant Supervised (Linux Only)

Requires specific OS (Debian 12 recommended):

# Install OS Agent
dpkg -i os-agent_1.x.x_linux_x86_64.deb

# Install Supervisor
docker run -d \
  --name hassio_supervisor \
  --privileged \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/run/dbus:/var/run/dbus \
  -v /mnt/data:/data \
  -e SUPERVISOR_SHARE=/mnt/data \
  -e SUPERVISOR_NAME=hassio_supervisor \
  ghcr.io/home-assistant/aarch64-hassio-supervisor:latest

6. Troubleshooting

USB Device Permissions (Z-Wave/Zigbee)

Issue: Permission denied on /dev/ttyUSB0 or /dev/ttyACM0

Solution:

# Find device
ls -la /dev/serial/by-id/

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Create udev rule (persistent naming)
echo 'SUBSYSTEM=="tty", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="zwave"' | sudo tee /etc/udev/rules.d/99-zwave.rules
sudo udevadm control --reload-rules

Dependency Installation Failures

Issue: Failed building wheel for ...

Solution:

# Install build dependencies
sudo apt-get install build-essential libssl-dev python3-dev

# Clear pip cache
pip cache purge

# Install with verbose output to identify missing libs
pip install -e . -v

Database Migration Issues

Issue: alembic.util.exc.CommandError or startup hangs

Solution:

# Reset database (WARNING: loses history)
rm config/home-assistant_v2.db

# Or migrate to MariaDB/PostgreSQL for production

Z-Wave JS Connection Failed

Issue: zwave_js_server.exceptions.NotConnected

Solution:

# Ensure Z-Wave JS server is running separately
npm install -g @zwave-js/server
zwave-server /dev/ttyUSB0

# Or use Docker
docker run -d \
  --name zwave-js-ui \
  --restart unless-stopped \
  -p 8091:8091 \
  -p 3000:3000 \
  --device=/dev/ttyUSB0 \
  -v zwave-config:/usr/src/app/store \
  zwavejs/zwave-js-ui:latest

Then configure integration to point to ws://localhost:3000.

Network Discovery Issues

Issue: Sonos, Cast, or other devices not discovered

Solution:

  • Ensure multicast/MDNS enabled on host
  • For Docker: Use --network host mode (required for discovery)
  • Check firewall: Allow ports 5353 (mDNS), 1900 (UPnP)

Frontend Not Loading

Issue: 404 on / or blank page

Solution:

# Rebuild frontend
script/build_frontend

# Or download production frontend
pip install homeassistant-frontend

High CPU/Memory Usage

Solution:

  • Disable history for high-frequency entities
  • Use exclude in recorder: configuration
  • Switch to MariaDB/PostgreSQL instead of SQLite for large databases
  • Limit logbook retention

Logs & Debug

# View logs
tail -f config/home-assistant.log

# Enable debug for specific component
# In configuration.yaml:
logger:
  default: info
  logs:
    homeassistant.components.zha: debug
    homeassistant.components.zwave_js: debug
    zwave_js_server: debug

Getting Help

← Project overviewView alternatives to home-assistant/core →