Skip to content

Installation

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

Installation

Step-by-step production deployment using Docker Compose.

Prerequisites

  • Docker Engine >= 24 and Docker Compose v2
  • A Linux host (amd64 or arm64)
  • (Optional) A Proxmox VE node reachable from the Docker host

1. Clone and Configure

git clone https://github.com/mtclab/homepilot-core-public.git
cd homepilot-core-public
cp .env.example .env

Edit .env. The minimum configuration for a zero-secrets deployment:

HP_DAEMON_PORT=8000
HP_PROXMOX_HOST=pve.example.local
HP_PROXMOX_VERIFY_SSL=false

All secrets (API signing key, admin secret, PVE token, etc.) are stored in the encrypted vault and resolved at runtime. See Configuration for details.

2. Bootstrap with hp init (recommended)

# Start the stack — passphrase auto-generates
docker compose up -d

# Initialize vault secrets and create admin token
docker compose exec backend hp init

# Verify
docker compose exec backend hp vault list

hp init sets all 5 vault secrets and creates an admin API token in one step.

Manual Bootstrap (advanced)

# Set each secret individually
docker compose exec -it backend hp vault set secret-key
docker compose exec -it backend hp vault set admin-secret
docker compose exec -it backend hp vault set pve-token        # {"token": "admin@pam!api=uuid"}
docker compose exec -it backend hp vault set jumpserver-token
docker compose exec -it backend hp vault set webhook-secret

# Create API token
docker compose exec backend hp token create

3. Start the Stack

docker compose up -d

The backend starts at http://localhost:8000 (UI at /ui).

The embedding service (BGE-M3) runs separately. Set HP_EMBEDDING_SERVICE_URL if it's on a different host or port. Default: http://llm-embed:8081/v1/embeddings.

4. Create the First API Token

docker compose exec backend hp token create

Output: hp_abc123...

Copy the token. In the web UI, you'll be redirected to /ui/settings on first visit — paste the token there and click Save.

Create a read-only token:

docker compose exec backend hp token create --scope read_only

5. Proxmox Integration

Create a least-privilege API token on Proxmox

On the Proxmox node:

# Create a dedicated user
pveum user add monitor@pam --comment "HomePilot API user"

# Create an API token
pveum user token add monitor@pam api --privsep 0

# Grant read access
pveum aclmod / --users monitor@pam --roles PVEAuditor

The token looks like: monitor@pam!api=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Store in vault

docker compose exec -it backend hp vault set pve-token
# Enter: {"token": "monitor@pam!api=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

Self-signed certificates

If your Proxmox node uses a self-signed TLS certificate, add:

HP_PROXMOX_VERIFY_SSL=false

Verify

docker compose exec backend hp inventory refresh

6. SSH Jump Server

The jump server relays SSH connections to managed hosts without exposing private keys.

Enable

HP_JUMP_ENABLED=true
HP_JUMP_TOKEN=${JUMPSERVER_AUTH_TOKEN}   # same secret on both sides

Add the relay key to managed hosts

# Get the public key
docker compose exec jumpserver cat /root/.ssh/id_ed25519.pub

# Add to each managed host
echo "<public key>" >> ~/.ssh/authorized_keys

Register host keys

docker compose exec jumpserver ssh-keyscan -H <host-ip> >> /etc/ssh/ssh_known_hosts

7. MCP Server Configuration

stdio (local)

{
  "mcpServers": {
    "homepilot": { "command": "hp", "args": ["mcp-serve"] }
  }
}

HTTP (remote)

Add to docker-compose.override.yml:

services:
  mcp:
    image: ghcr.io/mtclab/homepilot-core-public:${HP_IMAGE_TAG:-latest}
    command: ["hp", "mcp-serve", "--transport", "http", "--host", "0.0.0.0", "--port", "9000"]
    ports:
      - "9000:9000"
    volumes:
      - hp-data:/home/homepilot/.hp
    env_file:
      - .env
    environment:
      HP_MCP_TOKEN: ${HP_MCP_TOKEN}

Client config:

{
  "mcpServers": {
    "homepilot": {
      "url": "http://homepilot.example.com:9000/mcp",
      "headers": { "Authorization": "Bearer <HP_MCP_TOKEN>" }
    }
  }
}

Environment Variables

Variable Default Description
HP_IMAGE_TAG latest Docker image tag
HP_DAEMON_PORT 8000 Host port
HP_SECRET_KEY — Signs API tokens (required in production; auto-generated in dev)
HP_VAULT_PASSPHRASE — Vault encryption passphrase (auto-generated if not set)
HP_VAULT_PASSPHRASE_FILE — Path to passphrase file (overrides HP_VAULT_PASSPHRASE)
HP_PROXMOX_HOST — Proxmox VE hostname or IP
PVE_API_TOKEN — Proxmox API token (user@realm!tokenid=uuid)
HP_PROXMOX_VERIFY_SSL true Set false for self-signed certs
HP_JUMP_ENABLED false Enable SSH jump server relay
HP_JUMP_TOKEN — Auth token shared between backend and jump server
JUMPSERVER_AUTH_TOKEN — Jump server auth token (same as HP_JUMP_TOKEN)
HP_ARTIFACTS_REMOTE — Git remote URL for artifact backup
HP_ARTIFACTS_SSH_KEY — Path to SSH deploy key for artifact push
HP_MCP_TOKEN — Auth token for MCP HTTP endpoint
HP_RATE_LIMIT 60 Max requests per IP per minute
HP_CORS_ORIGINS * Comma-separated allowed CORS origins
HP_INVENTORY_INTERVAL_SECONDS 300 Inventory reconciler interval
HP_DRIFT_INTERVAL_SECONDS 1800 Drift reconciler interval
HP_AUTO_APPLY_ENABLED false Enable auto-apply reconciler
HP_AUTO_APPLY_INTERVAL_SECONDS 300 Auto-apply reconciler interval
HP_EMBEDDING_SERVICE_URL http://llm-embed:8081/v1/embeddings Primary embedding endpoint
HP_EMBEDDING_MODEL bge-m3 Model name for primary embedding service
HP_EMBEDDING_FALLBACK_URL http://localhost:11434/api/embeddings Fallback embedding endpoint
HP_EMBEDDING_FALLBACK_MODEL nomic-embed-text Model name for fallback

Deploy and Rollback

# Deploy
HP_IMAGE_TAG=v2.2.0 docker compose up -d backend

# Rollback
HP_IMAGE_TAG=v2.1.0 docker compose up -d backend

Migrations run automatically on startup.

Troubleshooting

Symptom Likely cause Fix
401 on all API calls Token not set or expired Run hp token create
403 on write operations Token scope is read_only Create a token with --scope read,write
Inventory shows 0 hosts Proxmox not configured Set HP_PROXMOX_HOST + token; run hp inventory refresh
Vault errors on start Passphrase not set Auto-generated in v2.2+; for manual setup, set HP_VAULT_PASSPHRASE
SSH failures Jump server key not in authorized_keys Add relay public key to managed hosts
Artifact push fails Deploy key permissions Check key has write access; push failures are non-fatal

See Also

  • Configuration — Vault system, zero-secrets deployment, all config options
  • Security — Auth model, RBAC scopes, token management

Clone this wiki locally