deploy/ — VM deployment for AZ One Health SentinelThis document covers everything that’s needed to take a fresh
Ubuntu 24.04 VM from apt update to a running deployment of:
mcp/ (vectorsurv-mcp,
knowledge-graph-mcp, great-az-tick-check-mcp, nws-heatrisk-mcp,
mag-hrn-mcp, adhs-mcp, 211-az-mcp, whispers-mcp, inaturalist-mcp,
sms-entry-mcp, wearable-mcp)agents/src/onehealth_agents/api/ running
under uvicorn as a systemd unitapp/, statically exported
and served by nginx with optional Let’s Encrypt TLSschema/)The provisioning is fully automated via the Ansible playbook in
../ansible/ — run one command, get a working host.
| 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:
Other distributions are not supported by the playbook; the manual steps below should translate.
On your workstation (not the VM):
ssh access to the VM as a user with sudoOn the VM:
sudo# 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:
claude on the deploy user’s $PATH, with all eleven MCP servers
registered (claude mcp list shows them).https://<your-domain>/ serving the Next.js app.https://<your-domain>/docs/ serving the MkDocs documentation site.https://<your-domain>/api/v1/healthz returning {"status":"ok"}.psql -U onehealth epihack working.systemd units enabled: onehealth-api, nginx,
postgresql, onehealth-mcp@<name> (one per MCP server, if
long-lived streamable-http transport is enabled).| 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. |
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.
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.
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.
| 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. |
../ansible/ — the Ansible playbook.../plan/06-mobile-app.md — the
privacy contract the app enforces.../plan/07-auth.md — Supabase Auth
integration; the VM holds the JWT-validation config, not the
Supabase project itself.../api/openapi.yaml — the HTTP contract
the FastAPI backend serves.