deploy/ — VM deployment for AZ One Health Sentinel

This document covers everything that’s needed to take a fresh Ubuntu 24.04 VM from apt update to a running deployment of:

The provisioning is fully automated via the Ansible playbook in ../ansible/ — run one command, get a working host.

VM sizing

Profile Use case vCPU RAM Disk
Dev / demo One person clicking through the app 2 4 GB 40 GB
Pilot One county + 10 CHWs 4 8 GB 100 GB
Phase 3 Maricopa + Coconino + agency dashboards 8 16 GB 250 GB
Statewide Phase 4 — 15 counties 16 32 GB 500 GB + S3

Notes:

Supported OS

Other distributions are not supported by the playbook; the manual steps below should translate.

Prerequisites

On your workstation (not the VM):

On the VM:

Quick start (Ansible)

# 1. From your workstation, clone the repo
git clone https://github.com/tyson-swetnam/epihack-2026.git
cd epihack-2026/ansible

# 2. Copy the example inventory and edit it
cp inventory.example.yml inventory.yml
$EDITOR inventory.yml          # set ansible_host + ansible_user

# 3. Copy the example vars and fill in secrets
cp group_vars/all.yml          group_vars/all.local.yml
cp group_vars/all.vault.example.yml  group_vars/all.vault.yml
$EDITOR group_vars/all.vault.yml
ansible-vault encrypt group_vars/all.vault.yml

# 4. Install required Ansible Galaxy collections
ansible-galaxy install -r requirements.yml

# 5. Run the playbook end-to-end
ansible-playbook -i inventory.yml playbook.yml --ask-vault-pass

About 10–15 minutes later, the VM has:

What the playbook does, role by role

Role What
common Base packages (git, curl, ca-certs, jq, …), the onehealth deploy user + SSH key, UFW firewall (22, 80, 443), fail2ban on SSH, swap if missing, timezone.
node Node.js 20 LTS via NodeSource, npm global prefix at ~/.npm-global so the deploy user can install packages without sudo.
python Python 3.11+ (Ubuntu 24.04 ships 3.12), the uv package manager.
postgres PostgreSQL 16, a onehealth database + role, pg_hba.conf for local trust + scram-sha-256 from app.
repo Clone the EpiHack repo to /srv/onehealth/epihack-2026. Idempotent — re-runs pull.
claude_code npm install -g @anthropic-ai/claude-code for the deploy user. Writes ~/.claude/settings.json with project-default model + ANTHROPIC_API_KEY from the vault.
mcp_servers uv sync each mcp/<name>-mcp/. Writes a ~/.claude.json snippet registering each server via stdio. Optional: systemd units for streamable-http mode.
fastapi uvicorn systemd unit running onehealth_agents.api:app on 127.0.0.1:8000. Reads SUPABASE_URL / JWT-validation config from the vault.
app npm ci && npm run gen:api && npm run build in app/. Static export lands in app/out/.
docs Builds the MkDocs Material site (docs/ + mkdocs.yml) into site/ with the pinned docs/requirements.txt toolchain, so nginx can serve it at /docs/. The same tree GitHub Pages publishes to gh-pages/docs/. Skip with serve_docs: false.
nginx nginx reverse-proxies /api/ → 127.0.0.1:8000, serves / from the static export, and serves /docs/ (MkDocs), /dashboard/, /query/ from the repo. Lets-Encrypt-ready via certbot --nginx.

DNS + TLS

Point an A record at the VM’s public IP before running the playbook (or run the playbook first and add the record afterwards). Once DNS resolves, the nginx role can issue a Let’s Encrypt cert:

ssh onehealth@your-host
sudo certbot --nginx -d sentinel.example.org

The playbook can also do this automatically when tls_email is set in the vault and tls_enabled: true in group_vars/all.yml.

Cloud provider templates

The playbook is provider-agnostic — any VM with SSH + sudo works. For convenience, deploy/providers/ holds minimal templates for the cloud the user happens to have:

Provider Template Status
AWS EC2 (Ubuntu 24.04, t3.medium) providers/aws-ec2.md TODO
DigitalOcean Droplet providers/digitalocean.md TODO
Linode providers/linode.md TODO
OCI Always Free providers/oracle-cloud.md TODO
Self-host (bare metal / Proxmox) providers/self-host.md TODO

Adding a provider template is a 5-minute job — feel free to drop one as a PR.

Manual install (no Ansible)

If you’d rather provision by hand, every step in the playbook is a documented Ansible task. Read ../ansible/roles/<name>/tasks/main.yml in order: common → node → python → postgres → repo → claude_code → mcp_servers → ducklake → mongodb → fastapi → app → docs → nginx. Each task corresponds to one shell command on the VM.

Operations

Task How
Re-deploy after a git pull on main ansible-playbook -i inventory.yml playbook.yml --tags repo,fastapi,app
Rotate the Anthropic API key Update the value in group_vars/all.vault.yml, then ansible-playbook ... --tags claude_code
Restart the FastAPI backend systemctl restart onehealth-api
Tail logs journalctl -u onehealth-api -f
Re-issue TLS cert certbot renew (cron-managed by default)
Back up Postgres pg_dump -U onehealth epihack \| gzip > backup-$(date +%F).sql.gz. Snapshot the DuckLake Parquet object store separately.