Self-Hosted Quick Start

Last updated: 2026-05-07 06:53:50

self-hosting quickstart deployment

Huitzo Self-Hosted Quick Start Guide¶

Deploy the Huitzo Operating System on your infrastructure in under 15 minutes.

Prerequisites Checklist¶

Before you begin, ensure you have:

Hardware: 4+ CPU cores, 8+ GB RAM, 50+ GB disk space
Operating System: Linux (Ubuntu 22.04+ recommended) or macOS
Docker: Version 28.0 or newer (Install Docker)
Docker Compose: Version 2.28 or newer (Install Compose)
License Key: From Huitzo (contact [email protected] if you don't have one)
Internet Access: For initial setup and license validation

Verify your environment:

# Check Docker version
docker --version
# Should show: Docker version 28.x.x or higher

# Check Docker Compose version
docker compose version
# Should show: Docker Compose version v2.28.x or higher

# Check available resources
docker system info | grep -E "CPUs|Total Memory"
# Should show: 4+ CPUs and 8+ GB memory

Step 1: Download Deployment Files¶

Create a directory for Huitzo and download the deployment configuration:

# Create deployment directory
mkdir -p ~/huitzo-deployment
cd ~/huitzo-deployment

# Download docker-compose.yml
curl -sSL https://get.huitzo.com/docker-compose.yml -o docker-compose.yml

# Download environment template
curl -sSL https://get.huitzo.com/.env.example -o .env

# Verify files downloaded successfully
ls -lh
# Should show: docker-compose.yml and .env

Alternative (if URLs not available): Copy files from the Huitzo repository:

cp /path/to/huitzo-repo/deploy/compose/docker-compose.yml .
cp /path/to/huitzo-repo/.env.example .env

Step 2: Configure Environment¶

Edit .env with your configuration. Required settings:

# Open .env in your preferred editor
nano .env  # or vim, code, etc.

Minimum required configuration:

# =============================================================================
# Required: License Key (from Huitzo)
# =============================================================================
HUITZO_LICENSE_KEY=your-license-key-here

# =============================================================================
# Required: Security
# =============================================================================
# Generate a random secret key (run this command):
# openssl rand -hex 32
HUITZO_SECRET_KEY=your-random-secret-key-change-me

# =============================================================================
# Required: Database Password
# =============================================================================
POSTGRES_PASSWORD=your-secure-database-password

Generate a secure secret key:

# Run this command and paste the output into HUITZO_SECRET_KEY
openssl rand -hex 32

Optional: Email notifications (recommended for production)

# SendGrid configuration (for notifications)
SENDGRID_API_KEY=SG.your-sendgrid-api-key
HUITZO_EMAIL_FROM=[email protected]

Optional: LLM providers (for AI features)

# OpenAI
OPENAI_API_KEY=sk-your-openai-key

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

Save and close the file (Ctrl+X, then Y, then Enter in nano).

Step 3: Start Huitzo¶

Launch all services with a single command:

# Start Huitzo in detached mode
docker compose up -d

# Expected output:
# [+] Running 5/5
#  ✔ Network huitzo-deployment_default  Created
#  ✔ Container huitzo-postgres          Started
#  ✔ Container huitzo-redis             Started
#  ✔ Container huitzo-app               Started
#  ✔ Container huitzo-worker            Started

Initial startup takes 30-60 seconds while: - Docker downloads images (if not cached) - Database initializes - Backend validates license and activates machine

Step 4: Verify Installation¶

Check that all services are running:

# Check service status
docker compose ps

# Expected output:
# NAME                 IMAGE                    STATUS
# huitzo-app           huitzo/huitzo:latest    Up 2 minutes (healthy)
# huitzo-worker        huitzo/huitzo:latest    Up 2 minutes
# huitzo-postgres      postgres:17-alpine       Up 2 minutes (healthy)
# huitzo-redis         redis:8-alpine           Up 2 minutes (healthy)

All services should show "Up" status.

Check the health endpoint:

# Test the API health endpoint
curl -s http://localhost:8080/health | jq

# Expected output:
# {
#   "status": "healthy",
#   "version": "2.0.0",
#   "services": {
#     "database": "healthy",
#     "redis": "healthy",
#     "worker": "healthy"
#   }
# }

If health check fails, see Troubleshooting section below.

Step 5: Access Huitzo¶

Huitzo is now running! Access it at:

WebCLI: http://localhost:8080
API Documentation: http://localhost:8080/docs
Health Check: http://localhost:8080/health

First login credentials: - Default admin user is created automatically - Check the logs for credentials:

docker compose logs app | grep -i "admin user created"
# Output: Admin user created: [email protected] / [generated-password]

Change the default password immediately after first login.

Step 6: Install Intelligence Packs¶

Install your first Intelligence Pack:

# Method 1: Via API (recommended)
curl -X POST http://localhost:8080/api/v1/packs/install \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example-pack", "version": "latest"}'

# Method 2: Via file upload
# 1. Copy pack file to ./packs directory
mkdir -p ./packs
cp /path/to/your-pack.tar.gz ./packs/

# 2. Restart services to load packs
docker compose restart app worker

Verify packs are loaded:

curl -s http://localhost:8080/api/v1/packs | jq '.data[].name'

Production Checklist¶

Before going to production, complete these additional steps:

1. Enable HTTPS¶

Put Huitzo behind a reverse proxy with TLS. Example with Nginx:

# /etc/nginx/sites-available/huitzo
server {
    listen 443 ssl http2;
    server_name huitzo.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/huitzo.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/huitzo.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Configure Backups¶

Set up automated daily backups:

#!/bin/bash
# /opt/huitzo/backup.sh

BACKUP_DIR="/backup/huitzo"
DATE=$(date +%Y%m%d-%H%M%S)

# Backup PostgreSQL
docker compose exec -T postgres pg_dump -U huitzo huitzo | gzip > "$BACKUP_DIR/db-$DATE.sql.gz"

# Backup data directories
tar -czf "$BACKUP_DIR/data-$DATE.tar.gz" ./data

# Keep only last 7 days of backups
find "$BACKUP_DIR" -name "*.gz" -mtime +7 -delete

echo "Backup completed: $DATE"

Add to cron:

# Run daily at 2 AM
0 2 * * * /opt/huitzo/backup.sh

3. Configure Monitoring¶

Set up health check monitoring:

#!/bin/bash
# /opt/huitzo/healthcheck.sh

if ! curl -f -s http://localhost:8080/health > /dev/null; then
    echo "Huitzo health check failed!"
    # Send alert (email, Slack, PagerDuty, etc.)
    exit 1
fi

Add to cron (check every 5 minutes):

*/5 * * * * /opt/huitzo/healthcheck.sh

4. Configure Log Rotation¶

Add Docker log rotation in /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Restart Docker:

sudo systemctl restart docker

5. Update Docker Compose¶

Update the docker-compose.yml to bind to localhost only (security):

services:
  app:
    ports:
      - "127.0.0.1:8080:8080"  # Only accessible from localhost

This ensures Huitzo is only accessible through your reverse proxy.

Troubleshooting¶

Services won't start¶

# Check logs for all services
docker compose logs

# Check specific service
docker compose logs app
docker compose logs postgres
docker compose logs redis
docker compose logs worker

# Common issues:
# - Invalid license key → Check HUITZO_LICENSE_KEY in .env
# - Database connection failed → Check POSTGRES_PASSWORD matches
# - Port already in use → Change port in docker-compose.yml

License validation failed¶

# Check license key format
echo $HUITZO_LICENSE_KEY

# Test connectivity to Keygen
curl -I https://api.keygen.sh/v1/ping

# Check backend logs for license errors
docker compose logs app | grep -i license

# Common issues:
# - No internet connection → Ensure outbound HTTPS is allowed
# - Invalid license key → Contact [email protected]
# - Firewall blocking → Allow outbound to api.keygen.sh

Health check returns unhealthy¶

# Check database connection
docker compose exec app pg_isready -h postgres -U huitzo
# Should return: postgres:5432 - accepting connections

# Check Redis connection
docker compose exec app redis-cli -h redis ping
# Should return: PONG

# Check backend logs
docker compose logs app --tail 50

Worker not processing tasks¶

# Check worker logs
docker compose logs worker

# Restart worker
docker compose restart worker

# Verify Redis connection
docker compose exec worker redis-cli -h redis ping

Out of disk space¶

# Check disk usage
df -h

# Clean up Docker
docker system prune -a

# Check data directory size
du -sh ./data/*

Updating Huitzo¶

To update to the latest version:

# Pull latest images
docker compose pull

# Stop services
docker compose down

# Start with new images
docker compose up -d

# Verify update
curl -s http://localhost:8080/health | jq '.version'

Database migrations run automatically on startup.

Uninstalling¶

To completely remove Huitzo:

# Stop all services
docker compose down

# Remove data (⚠️ IRREVERSIBLE - backup first!)
docker compose down -v
rm -rf ./data

# Remove deployment directory
cd ..
rm -rf ~/huitzo-deployment

Getting Help¶

If you encounter issues:

Check logs: docker compose logs
Review documentation: https://docs.huitzo.ai
Contact support: [email protected]
Emergency support: For production issues, contact [email protected]

Next Steps¶

Detailed Deployment Guide - Complete configuration options
Operations Guide - Day-to-day operations and maintenance
Observability Guide - Monitoring, logging, and metrics
API Documentation - API reference
SDK Documentation - Build Intelligence Packs

Need a fully managed solution? Consider Huitzo Cloud for a hassle-free experience with automatic updates, backups, and 24/7 support.