claude-home/.claude/plans/home-assistant-deployment-guide.md

Home Assistant Deployment Architecture

Recommended Deployment: Podman Container on Proxmox

Why Podman Container vs Home Assistant OS?

• Flexibility: Full control over host system, easier customization
• Integration: Better integration with existing Proxmox infrastructure
• Backup: Standard container backup/restore workflows
• Resources: More efficient resource usage
• Updates: Granular update control
• GPU Support: Already proven working with your Tdarr setup

Container Architecture

# Core Home Assistant container
podman run -d --name homeassistant \
  --restart=unless-stopped \
  -p 8123:8123 \
  -v /path/to/config:/config \
  -v /etc/localtime:/etc/localtime:ro \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \  # If you add Zigbee/Z-Wave
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Supporting Services Architecture

# docker-compose.yml for full stack
version: '3.8'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

  # Optional: Local database instead of SQLite
  postgres:
    container_name: ha-postgres
    image: postgres:15
    environment:
      POSTGRES_DB: homeassistant
      POSTGRES_USER: homeassistant
      POSTGRES_PASSWORD: your-secure-password
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    ports:
      - "5432:5432"

  # Optional: MQTT broker for device communication
  mosquitto:
    container_name: ha-mosquitto
    image: eclipse-mosquitto:latest
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  # Optional: Node-RED for visual automation development
  node-red:
    container_name: ha-node-red
    image: nodered/node-red:latest
    restart: unless-stopped
    ports:
      - "1880:1880"
    volumes:
      - ./node-red-data:/data

Migration Strategy

Phase 1: Parallel Setup (Recommended)

1. Deploy HA alongside Apple Home (don't disturb current setup)
2. Start with 1-2 test devices (re-pair a couple of sensors)
3. Build basic automations to validate functionality
4. Test for 1-2 weeks to ensure stability

Phase 2: Gradual Migration

1. Re-pair devices in groups (sensors first, then bulbs, etc.)
2. Migrate automations one by one
3. Keep Apple Home as backup until confident

Phase 3: Full Cutover

1. Remove devices from Apple Home
2. Decommission Apple TV hub role (keep as media device)
3. Full automation implementation

Device Integration Strategy

Matter Devices (Your Current Setup)

• Direct Integration: HA's Matter support is mature as of 2024
• No Hub Required: HA can be the Matter controller
• Thread Network: Can share Thread network between platforms during migration

Philips Hue Bridge

• Option 1: Keep bridge, integrate via Hue integration (easier)
• Option 2: Direct Zigbee control (requires Zigbee coordinator)
• Recommendation: Keep bridge initially, migrate later if needed

Future Expansion Options

• Zigbee: Add Zigbee coordinator for non-Matter devices
• Z-Wave: Add Z-Wave stick for legacy devices
• WiFi Devices: Direct integration via HA's vast library
• Custom Integrations: HACS (Home Assistant Community Store)

Automation Examples You Can Build

Complex Scheduling

# Advanced morning routine with conditions
automation:
  - alias: "Smart Morning Routine"
    trigger:
      - platform: time
        at: "06:30:00"
    condition:
      - condition: state
        entity_id: binary_sensor.workday
        state: 'on'
      - condition: state
        entity_id: person.your_name
        state: 'home'
    action:
      - service: light.turn_on
        target:
          entity_id: light.bedroom_lights
        data:
          brightness_pct: 30
          color_temp: 400
      - delay: "00:15:00"
      - service: light.turn_on
        data:
          brightness_pct: 80

Presence Detection

# Multi-factor presence with phone + door sensors
automation:
  - alias: "Arrival Detection"
    trigger:
      - platform: state
        entity_id: person.your_name
        to: 'home'
      - platform: state
        entity_id: binary_sensor.front_door
        to: 'on'
    condition:
      - condition: state
        entity_id: person.your_name
        state: 'home'
    action:
      - service: scene.turn_on
        target:
          entity_id: scene.arrival_lights
      - service: climate.set_temperature
        target:
          entity_id: climate.main_thermostat
        data:
          temperature: 72

Resource Requirements

Minimum Specs

• CPU: 2 cores
• RAM: 2GB
• Storage: 20GB
• Network: Gigabit recommended for media streaming integration

Your Proxmox Environment

• Should handle HA easily alongside existing containers
• Consider dedicating specific resources if running many integrations
• Network mode: host recommended for device discovery