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

```bash
# 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

```yaml
# 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
```yaml
# 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
```yaml
# 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