Skip to content

Production Deployment

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

Production Deployment

Real-world deployment notes from running HomePilot in production.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Reverse     │     │  HomePilot    │     │  Proxmox VE      │
│   Proxy       │────▶│  Backend      │────▶│  3-Node Cluster  │
│  (HTTPS/TLS)  │     │  (Docker)     │     │  (API port 8006) │
└──────────────┘     └──────┬───────┘     └──────────────────┘
                           │
                    ┌──────▼───────┐
                    │  Database     │
                    │  (PostgreSQL) │
                    └──────────────┘

Key Environment Variables

Variable Purpose
HP_PROXMOX_HOST Proxmox VE hostname or IP
HP_PROXMOX_VERIFY_SSL Set false for self-signed certs
HP_EMBEDDING_SERVICE_URL Embedding service endpoint
HP_EMBEDDING_MODEL Model name (e.g., nomic-embed-text)
HP_EMBEDDING_FALLBACK_URL Fallback embedding endpoint
HP_JUMP_ENABLED Enable SSH jump server
HP_VAULT_PASSPHRASE_FILE Path to vault passphrase file

Zero-Secrets Deployment

No secrets in .env files. All sensitive values are stored in the age-encrypted vault:

docker compose exec backend hp init          # bootstrap all secrets
docker compose exec backend hp vault list     # verify vault contents

Reverse Proxy (HTTPS)

HomePilot should sit behind a reverse proxy with TLS in production:

server {
    listen 443 ssl http2;
    ssl_certificate     /etc/ssl/certs/proxy.crt;
    ssl_certificate_key /etc/ssl/private/proxy.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    add_header          Strict-Transport-Security "max-age=63072000" always;

    location / {
        proxy_pass http://backend:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Redirect HTTP → HTTPS:

server {
    listen 80;
    return 301 https://$host$request_uri;
}

Embedding Service

HomePilot supports a primary and fallback embedding endpoint:

  • Primary: Fast local service (e.g., BGE-M3 on GPU)
  • Fallback: Ollama with nomic-embed-text (768-dim, CPU-friendly)
HP_EMBEDDING_SERVICE_URL=http://host.docker.internal:11435/api/embeddings
HP_EMBEDDING_MODEL=nomic-embed-text

Monitoring

See the HomePilot Agent Monitoring wiki for Zabbix integration with Proxmox VE nodes and HomePilot services.

See Also

Clone this wiki locally