Skip to content

Deployment

Jump to bottom
ollikurki edited this page May 20, 2026 · 1 revision

Deployment

Complete guide for deploying HomePilot Agent with Docker Compose.

Hardware Requirements

Component Minimum Recommended
CPU 4 cores 8+ cores
RAM 16 GB 32 GB
GPU 1× RTX 3060 (12GB) 1× RTX 4000 Ada SFF (20GB)
Storage 50 GB 100 GB+ SSD
Network LAN access to Proxmox LAN + internet for updates

The LLM service (Qwen3-14B Q8_0) requires ~15 GB VRAM. Embedding model (BGE-M3) needs ~2 GB VRAM on a second GPU or can share the primary GPU.

Prerequisites

  • Docker Engine 24+ with Docker Compose v2
  • NVIDIA Container Toolkit (for GPU profiles)
  • wget or curl for model downloads
  • Network access to Proxmox VE host(s)

Verify NVIDIA runtime:

docker run --rm --runtime=nvidia nvidia/cuda:12.0-base nvidia-smi

Environment Configuration

1. Create .env file

cp .env.example .env

2. Required Variables

Variable Description Example
N8N_ENCRYPTION_KEY Required — n8n fails without it openssl rand -hex 32
N8N_API_KEY For import-workflows.sh Generate in n8n Settings → API
SEARXNG_SECRET_KEY SearXNG secret openssl rand -hex 32

3. Service Configuration Variables

Variable Description
N8N_HOST n8n hostname (default: localhost)
N8N_PORT n8n port (default: 5678)
N8N_PROTOCOL http or https
N8N_WEBHOOK_URL Public URL for webhook callbacks

4. Secrets (stored in n8n credential store, not .env)

These are configured in the n8n UI after deployment — do not put real values in .env:

Secret Purpose
HomePilot MCP Token (read-only) Query HomePilot infrastructure data
HomePilot MCP Token (read-write) Propose artifacts, record facts
Matrix Access Token Bot posts to Matrix room
HP Webhook Secret Validate incoming HomePilot webhooks
Telegram Bot Token Telegram bot authentication

Docker Compose Profiles

Core (default)

n8n, SearXNG, Radicale — no GPU required:

docker compose up -d

With GPU

Adds LLM inference services:

docker compose --profile gpu up -d

With Voice

Adds Whisper STT and Piper TTS:

docker compose --profile voice up -d

Full Stack

docker compose --profile gpu --profile voice up -d

The llm service takes 1–3 minutes to load the model. n8n waits for LLM health check before starting.

GPU Layout

The default configuration uses separate GPUs for LLM and embedding services:

Service GPU VRAM Needed Env Var
llm (Qwen3-14B) GPU 0 ~15 GB NVIDIA_VISIBLE_DEVICES=0
llm-embed (BGE-M3) GPU 1 ~2 GB NVIDIA_VISIBLE_DEVICES=1

To change GPU assignment, edit NVIDIA_VISIBLE_DEVICES in .env.

Model Download

# Download Qwen3-14B Q8_0 (~15 GB)
scripts/download-model.sh

# Download BGE-M3 embedding model
wget -O models/bge-m3.gguf \
  https://huggingface.co/CompendiumLabs/bge-m3-gguf/resolve/main/bge-m3-Q8_0.gguf

The download script resumes if interrupted and skips if the file exists.

Monitoring Stack (Zabbix)

Deploy Zabbix as a separate overlay:

docker compose -f docker-compose.yml \
  -f docker-compose.monitoring.yml up -d

This adds:

  • Zabbix Server (PostgreSQL backend)
  • Zabbix Web UI
  • Zabbix Agent2 (on the host)
  • Caddy TLS reverse proxy (optional)

See Monitoring for full Zabbix configuration.

Post-Deploy Setup

n8n Credentials

Open http://localhost:5678 (or your configured URL) and create these credentials:

Credential Name Type Notes
Telegram Bot Telegram API Bot token from BotFather
Qwen LLM (llama.cpp) OpenAI API Base URL: http://llm:8080/v1, any API key
HomePilot MCP Token (read-only) HTTP Bearer Auth Read-only infrastructure token
HomePilot MCP Token (read-write) HTTP Bearer Auth Read-write token for mutations
Matrix Bot HTTP Bearer Auth Matrix access token
HP Webhook Secret HTTP Header Auth Header: X-HP-Webhook-Secret
Radicale Calendar HTTP Basic Auth Calendar credentials from .env

Import Workflows

# Requires N8N_API_KEY in .env
scripts/import-workflows.sh

Activate Workflows

In n8n UI, activate in this order:

  1. Artifact Notification — passive webhook receiver
  2. Morning Drift Briefing — daily cron at 08:00
  3. Calendar → HomePilot Trigger — polls Radicale every 5 min
  4. Chat Assistant (Read-Only) — Telegram listener
  5. Personal Assistant — full AI Agent (activate last, after testing)

Wire HomePilot Webhook

In your HomePilot deployment, set:

HP_EVENTS_WEBHOOK_URL=http://<your-agent-host>:5678/webhook/artifact-proposed
HP_EVENTS_WEBHOOK_SECRET=<same value as HP Webhook Secret credential>

Troubleshooting

LLM won't start

  • Verify GPU visibility: nvidia-smi
  • Check VRAM: Qwen3-14B Q8_0 needs ~15 GB
  • Check NVIDIA_VISIBLE_DEVICES in .env

n8n not connecting to LLM

  • Ensure llm container is healthy: docker compose ps llm
  • Verify http://llm:8080/v1 responds from n8n container
  • Check n8n logs: docker compose logs n8n

Zabbix not starting

  • Verify PostgreSQL is running: docker compose logs zabbix-postgres
  • Check ZABBIX_DB_PASSWORD matches in secret file and .env

Updating

git pull
docker compose pull
docker compose up -d

For Zabbix stack:

docker compose -f docker-compose.yml \
  -f docker-compose.monitoring.yml pull
docker compose -f docker-compose.yml \
  -f docker-compose.monitoring.yml up -d

Clone this wiki locally