Skip to content

Deployment

Heka is deployed as a single Fly.io machine (heka-operator) with an attached volume for the SQLite database.

Architecture

Internet ──► Fly.io Proxy ──► heka-operator (single machine)
                                  ├─ FastAPI (port 8000)
                                  ├─ SQLite on /data/ volume
                                  └─ Static frontend (Vite build)

Deploy to production

fly deploy --app heka-operator

The Dockerfile uses a multi-stage build:

  1. frontend — builds the React app with npm run build
  2. backend — installs Python dependencies with uv pip install
  3. final — copies both into a slim Python image

Fly.io configuration

Key settings in fly.toml:

  • App: heka-operator
  • Region: single region (Mexico City recommended for latency)
  • Machine: shared-cpu-1x, 512MB RAM
  • Volume: /data — persistent SQLite storage
  • Port: 8000 (internal), 443 (external via Fly proxy)

Database

The SQLite database lives at /data/heka_conversations.db on the Fly volume. Schema migrations run automatically on startup via init_db().

Access production database

# SSH into the machine
fly ssh console --app heka-operator

# Open the database
sqlite3 /data/heka_conversations.db

# Or run queries remotely
fly ssh console --app heka-operator -C "sqlite3 /data/heka_conversations.db '.tables'"

Backup

# Download the database
fly ssh sftp get /data/heka_conversations.db ./backup-$(date +%Y%m%d).db --app heka-operator

Environment secrets

Secrets are managed via Fly.io:

# Set a secret
fly secrets set META_ACCESS_TOKEN=your_token --app heka-operator

# List secrets (names only)
fly secrets list --app heka-operator

Required secrets:

Secret Description
META_PHONE_NUMBER_ID WhatsApp Business phone number ID
META_ACCESS_TOKEN Meta Graph API access token
META_VERIFY_TOKEN Webhook verification token
META_APP_SECRET App secret for webhook signature verification
ANTHROPIC_API_KEY Claude API key
JWT_SECRET_KEY JWT signing key
R2_ACCOUNT_ID Cloudflare R2 account
R2_ACCESS_KEY_ID R2 access key
R2_SECRET_ACCESS_KEY R2 secret key
R2_BUCKET_NAME R2 bucket name

Monitoring

# Live logs
fly logs --app heka-operator

# Machine status
fly status --app heka-operator

# Monitoring dashboard
# https://fly.io/apps/heka-operator/monitoring

Rollback

Fly.io keeps recent releases. To rollback:

# List releases
fly releases --app heka-operator

# Rollback to previous
fly deploy --app heka-operator --image registry.fly.io/heka-operator:deployment-PREVIOUS_ID