homeassistant-ai
diff --git a/‎tests/lab-setup/README.md‎
Lines changed: 64 additions & 50 deletions b/‎tests/lab-setup/README.md‎
Lines changed: 64 additions & 50 deletions
diff --git a/‎tests/lab-setup/setup-ha-mcp.sh‎
Lines changed: 88 additions & 26 deletions b/‎tests/lab-setup/setup-ha-mcp.sh‎
Lines changed: 88 additions & 26 deletions
@@ -2,95 +2,109 @@
 
 This directory contains scripts for setting up a persistent Home Assistant test environment, useful for demos, development, and integration testing.
 
+## Requirements
+
+- Ubuntu/Debian Linux server (tested on Debian 12)
+- Minimum specs: **2 vCPU, 4GB RAM, 20GB disk** (Home Assistant uses ~1.5GB RAM; 6GB swap is created automatically for headroom)
+- A non-root user with `sudo` access
+- Domain name pointing to the server's IP (for HTTPS; optional for local-only)
+- Ports **80** and **443** open inbound (for Caddy + Let's Encrypt)
+
 ## Quick Start
 
 ```bash
-# Download and run on a fresh Ubuntu/Debian server
+# 1. SSH in as a non-root user (e.g. the default GCP/AWS/Azure user)
+# 2. Download and run:
 curl -fsSL https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/tests/lab-setup/setup-ha-mcp.sh -o setup-ha-mcp.sh
 chmod +x setup-ha-mcp.sh
 sudo ./setup-ha-mcp.sh your-domain.example.com
 ```
 
+> **Important:** Use `sudo ./setup-ha-mcp.sh`, not `sudo su -` followed by `./setup-ha-mcp.sh`.
+> The script uses `$SUDO_USER` to identify which user to configure. Running as root directly loses that information and the script will exit with an error.
+>
+> If calling from a **root cron job**, set it explicitly:
+> `SUDO_USER=youruser ./setup-ha-mcp.sh your-domain.example.com`
+
+Setup takes about 3–10 minutes on subsequent runs. Allow up to 15 minutes on first install when the ~600 MB HA image must be pulled. Home Assistant starts automatically.
+
 ## What It Does
 
 The setup script is **idempotent** (safe to re-run) and performs:
 
-1. **Swap Configuration** - Creates 6GB swap for small VMs
-2. **Package Installation** - curl, git, ca-certificates, gnupg
-3. **Docker Installation** - Via official get.docker.com script
-4. **uv Installation** - Python package manager for running ha-mcp
-5. **ha-mcp Clone** - Clones the repository to `~/ha-mcp`
-6. **Crontab Setup** - Auto-starts on reboot + weekly reset (Mondays 3am)
-7. **Caddy Reverse Proxy** - HTTPS with automatic Let's Encrypt certificates
-8. **Unattended Upgrades** - Auto-updates system packages with auto-reboot at 4am
-9. **Container Cleanup** - Removes old HA containers
-10. **Start Test Environment** - Launches hamcp-test-env in background
-
-## Weekly Reset (Monday 3am)
-
-The lab environment automatically resets every Monday at 3am:
-- Pulls latest ha-mcp changes from git
-- Stops and removes Home Assistant containers
-- Prunes unused Docker images (prevents disk fill)
-- Restarts hamcp-test-env with fresh container
+1. **Swap** — Creates 6GB swap for small VMs
+2. **Packages** — Installs curl, git, ca-certificates, gnupg
+3. **Docker** — Via official get.docker.com script
+4. **uv** — Python package manager for running ha-mcp
+5. **ha-mcp repo** — Clones to `~/ha-mcp` (or pulls if it already exists)
+6. **Systemd service** — Creates `hamcp-demo.service` (starts on boot, restarts on failure) and `hamcp-demo-update.timer` (daily at 3am: git pull, docker image prune, service restart)
+7. **Caddy** — Reverse proxy with automatic Let's Encrypt TLS for your domain
+8. **Unattended upgrades** — Auto-updates OS packages, reboots at 4am if needed
+9. **Container cleanup** — Removes stale HA containers and any leaked processes
+10. **Start** — Launches `hamcp-demo` via systemd and waits for Home Assistant to become ready
 
-## Requirements
+## Access
 
-- Ubuntu/Debian Linux server
-- Root access (sudo)
-- Domain pointing to server (for HTTPS)
-- Ports 80/443 open (for Caddy/HTTPS)
-- Port 8123 (internal, for Home Assistant)
+After setup:
 
-## Usage
+| | URL |
+|---|---|
+| Local | http://localhost:8123 |
+| External | https://your-domain.example.com |
+| Credentials | `dev` / `dev` |
 
-```bash
-# With custom domain (HTTPS enabled)
-sudo ./setup-ha-mcp.sh my-ha-lab.example.com
+## Managing the Service
 
-# Without domain (local access only)
-sudo ./setup-ha-mcp.sh ""
-```
+```bash
+# Status
+sudo systemctl status hamcp-demo
 
-## Access
+# Restart (e.g. after manual code changes)
+sudo systemctl restart hamcp-demo
 
-After setup:
+# Live logs
+sudo journalctl -u hamcp-demo -f
 
-| Access | URL |
-|--------|-----|
-| Local | http://localhost:8123 |
-| External | https://your-domain.example.com |
-| Credentials | dev / dev |
+# Weekly update timer — next run and last result
+sudo systemctl list-timers hamcp-demo-update.timer
+sudo journalctl -u hamcp-demo-update --no-pager -n 20
+```
 
 ## Logs
 
 ```bash
+# Service log (startup, HA output, errors)
+sudo journalctl -u hamcp-demo -f
+
 # Home Assistant container logs
 docker logs -f $(docker ps --filter "ancestor=ghcr.io/home-assistant/home-assistant" -q)
-
-# Startup script log
-tail -f /tmp/hamcp.log
 ```
 
 ## Troubleshooting
 
-### Container not starting
+### Home Assistant not starting
 ```bash
-cat /tmp/hamcp.log
+sudo journalctl -u hamcp-demo --no-pager -n 50
 docker ps -a
 ```
 
 ### Caddy certificate issues
 ```bash
-sudo journalctl -u caddy -f
-sudo caddy validate --config /etc/caddy/Caddyfile
+sudo journalctl -u caddy --no-pager -n 30
+# Force renewal by restarting Caddy
+sudo systemctl restart caddy
 ```
 
 ### Restart the environment
 ```bash
-# Stop
-docker stop $(docker ps --filter "ancestor=ghcr.io/home-assistant/home-assistant" -q)
+sudo systemctl restart hamcp-demo
+```
 
-# Start
-cd ~/ha-mcp && HA_TEST_PORT=8123 ~/.local/bin/uv run hamcp-test-env --no-interactive &
+### Full reset (re-clone and restart from scratch)
+```bash
+sudo systemctl stop hamcp-demo
+docker ps -aq --filter "ancestor=ghcr.io/home-assistant/home-assistant" | xargs -r docker rm -f 2>/dev/null || true
+docker ps -aq --filter "ancestor=testcontainers/ryuk" | xargs -r docker rm -f 2>/dev/null || true
+rm -rf ~/ha-mcp
+sudo ./setup-ha-mcp.sh your-domain.example.com
 ```
@@ -22,6 +22,7 @@ error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }
 
 #=============================================================================
 [[ $EUID -ne 0 ]] && error "Run as root: sudo $0 [domain]"
+[[ "$SETUP_USER" == "root" ]] && error "Do not run as root directly. Use: sudo $0 [domain]\nIf calling from a root cron job, set: SUDO_USER=youruser $0 [domain]"
 info "Setting up ha-mcp test env for user: $SETUP_USER"
 info "Domain: $DOMAIN"
 
@@ -66,7 +67,7 @@ fi
 # 4. UV
 if [[ ! -f "$UV_PATH" ]]; then
     info "Installing uv..."
-    sudo -u "$SETUP_USER" bash -c 'curl -LsSf https://astral.sh/uv/install.sh | sh'
+    sudo -i -u "$SETUP_USER" bash -c 'curl -LsSf https://astral.sh/uv/install.sh | sh'
 else
     info "uv already installed"
 fi
@@ -82,15 +83,70 @@ else
 fi
 
 #=============================================================================
-# 6. CRONTAB (startup + weekly reset)
-info "Setting up crontab..."
-CRON_REBOOT="@reboot sleep 10 && cd $SETUP_HOME/ha-mcp && HA_TEST_PORT=$HA_PORT $UV_PATH run hamcp-test-env --no-interactive >> /tmp/hamcp.log 2>&1"
-CRON_WEEKLY="0 3 * * 1 cd $SETUP_HOME/ha-mcp && git pull --ff-only && docker stop \$(docker ps -q --filter ancestor=ghcr.io/home-assistant/home-assistant) 2>/dev/null; docker rm \$(docker ps -aq --filter ancestor=ghcr.io/home-assistant/home-assistant) 2>/dev/null; docker image prune -af 2>/dev/null; HA_TEST_PORT=$HA_PORT $UV_PATH run hamcp-test-env --no-interactive >> /tmp/hamcp.log 2>&1"
-(
-    sudo -u "$SETUP_USER" crontab -l 2>/dev/null | grep -v "hamcp-test-env" || true
-    echo "$CRON_REBOOT"
-    echo "$CRON_WEEKLY"
-) | sudo -u "$SETUP_USER" crontab -
+# 6. SYSTEMD SERVICE (replaces cron - ensures only one instance runs, auto-restarts)
+info "Setting up systemd service..."
+
+# Remove old cron entries if they exist (migration from cron-based setup)
+if sudo -u "$SETUP_USER" crontab -l 2>/dev/null | grep -q "hamcp-test-env"; then
+    sudo -u "$SETUP_USER" crontab -l 2>/dev/null | { grep -v "hamcp-test-env" || true; } | sudo -u "$SETUP_USER" crontab -
+fi
+
+cat > /etc/systemd/system/hamcp-demo.service << SVCEOF
+[Unit]
+Description=HA-MCP Demo Test Environment
+After=docker.service network-online.target
+Wants=network-online.target
+Requires=docker.service
+
+[Service]
+Type=simple
+User=${SETUP_USER}
+Group=${SETUP_USER}
+WorkingDirectory=${SETUP_HOME}/ha-mcp
+Environment=HA_TEST_PORT=${HA_PORT}
+ExecStart=${UV_PATH} run hamcp-test-env --no-interactive
+Restart=on-failure
+RestartSec=30s
+KillSignal=SIGINT
+TimeoutStopSec=60
+
+[Install]
+WantedBy=multi-user.target
+SVCEOF
+
+cat > /etc/systemd/system/hamcp-demo-update.service << SVCEOF
+[Unit]
+Description=HA-MCP Demo Weekly Update
+After=network-online.target docker.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/sudo -i -u ${SETUP_USER} /usr/bin/git -C ${SETUP_HOME}/ha-mcp pull --ff-only
+ExecStart=/usr/bin/docker image prune -af
+ExecStartPost=/usr/bin/systemctl restart hamcp-demo
+SVCEOF
+
+cat > /etc/systemd/system/hamcp-demo-update.timer << SVCEOF
+[Unit]
+Description=HA-MCP Demo Weekly Update Timer
+
+[Timer]
+OnCalendar=*-*-* 03:00:00
+AccuracySec=1h
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+SVCEOF
+
+# Remove sudoers rule if it exists from a previous install (no longer needed)
+rm -f /etc/sudoers.d/hamcp-demo
+
+systemctl daemon-reload
+systemctl enable hamcp-demo.service
+systemctl enable hamcp-demo-update.timer
+systemctl start hamcp-demo-update.timer
 
 #=============================================================================
 # 7. CADDY
@@ -146,32 +202,38 @@ APT::Periodic::AutocleanInterval "7";
 AUTOEOF
 
 #=============================================================================
-# 9. STOP OLD CONTAINERS
-info "Cleaning up old containers..."
+# 9. STOP OLD CONTAINERS + PROCESSES
+info "Cleaning up old containers and processes..."
+systemctl stop hamcp-demo 2>/dev/null || true
 docker ps -aq --filter "ancestor=ghcr.io/home-assistant/home-assistant" | xargs -r docker rm -f 2>/dev/null || true
+docker ps -aq --filter "ancestor=testcontainers/ryuk" | xargs -r docker rm -f 2>/dev/null || true
+pkill -u "$SETUP_USER" -f "hamcp-test-env" 2>/dev/null || true
 
 #=============================================================================
-# 10. START HA-MCP
-info "Starting hamcp-test-env..."
-sudo -u "$SETUP_USER" sg docker -c "cd $SETUP_HOME/ha-mcp && HA_TEST_PORT=$HA_PORT $UV_PATH run hamcp-test-env --no-interactive > /tmp/hamcp.log 2>&1 &"
+# 10. START HA-MCP VIA SYSTEMD
+info "Starting hamcp-demo service..."
+systemctl restart hamcp-demo.service
 
 #=============================================================================
 # 11. WAIT FOR HA
-info "Waiting for Home Assistant to start..."
-for i in {1..60}; do
+# On first install, the HA image (~600MB) must be pulled before the container
+# starts. Allow up to 15 minutes to cover both pull and boot time.
+info "Waiting for Home Assistant to start (up to 15 minutes on first install)..."
+HA_READY=0
+for i in {1..180}; do
     if curl -s -o /dev/null -w "%{http_code}" "http://localhost:$HA_PORT" 2>/dev/null | grep -qE "200|401"; then
+        HA_READY=1
         break
     fi
     echo -n "."
-    sleep 2
+    sleep 5
 done
 echo ""
 
 #=============================================================================
-# 11. VERIFY
-sleep 3
-if docker ps | grep -q "home-assistant"; then
-    CONTAINER=$(docker ps --filter "ancestor=ghcr.io/home-assistant/home-assistant" --format "{{.Names}}" | head -1)
+# 12. VERIFY
+if [[ $HA_READY -eq 1 ]]; then
+    CONTAINER=$(docker ps --format "{{.Image}}\t{{.Names}}" | awk -F'\t' '/home-assistant/{print $2}' | head -1)
     echo ""
     echo "=============================================="
     echo -e "${GREEN}Setup Complete!${NC}"
@@ -183,11 +245,11 @@ if docker ps | grep -q "home-assistant"; then
     echo "Credentials: dev / dev"
     echo ""
     echo "Logs:        docker logs -f $CONTAINER"
-    echo "Startup log: tail -f /tmp/hamcp.log"
+    echo "Service log: journalctl -u hamcp-demo -f"
     echo "=============================================="
 else
     echo ""
-    echo -e "${RED}Container not running!${NC}"
-    echo "Check logs: cat /tmp/hamcp.log"
-    exit 1
+    warn "Home Assistant did not respond within 15 minutes."
+    warn "The service is running — HA may still be starting (check: journalctl -u hamcp-demo -f)"
+    warn "If it stays down: journalctl -u hamcp-demo --no-pager -n 50"
 fi