[[
wikihub
]]
Search
⌘K
Explore
People
For Agents
Sign in
Explore
People
For Agents
Sign in
@jacobcole / picortex — planning / docs/runbooks/deploy.md
Suggest edit
Cancel
Submit suggestion
Title
Name
Note
--- visibility: public --- # Runbook: Deploy **Status:** Stub — finalized in [D1](../plans/2026-04-23-initial-roadmap.md#d1-deployment-target--runbook). Deployment target is open question Q3 in the PRD. Candidates: ## Option A — Hetzner sibling to jcortex - VPS at Hetzner, x86_64, Ubuntu 22.04+ - Alongside voice-assistant (jcortex) - Caddy for TLS; systemd for process supervision - Domain: `picortex.globalbr.ai` (Cloudflare A record, DNS-only) - Pros: Linux, cheap, full control; cgroups v2 + bubblewrap available - Cons: one more server to babysit ## Option B — Fly.io - Fly app, multi-region or single - Persistent volumes for chat home dirs - Fly handles TLS - Pros: minimal ops - Cons: systemd-free (use supercronic), Linux user model is the same, but Fly's per-instance FS is ephemeral unless volume-backed; need to mount volumes for chat homes ## Option C — HMA (Mac Mini) - Jacob's always-on Mac Mini (`sdmm291`) - Already runs many services; public access via Cloudflare Tunnel - Pros: no extra server - Cons: macOS doesn't have Linux users in the same way; `useradd`/`chmod 0700` model has to use macOS dscl + dseditgroup, more awkward; cgroups v2 unavailable **Working assumption:** Option A. Decide in D1. --- ## Deploy script (draft, Option A) ```bash # On laptop: git push origin main # On Hetzner VPS as root: cd /opt/picortex sudo -u picortex git pull sudo -u picortex npm ci sudo -u picortex npm run build systemctl restart picortex ``` ## Systemd unit (draft) ``` [Unit] Description=picortex After=network.target [Service] User=picortex WorkingDirectory=/opt/picortex Environment=NODE_ENV=production EnvironmentFile=/opt/picortex/.env ExecStart=/usr/bin/node dist/server.js Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target ``` ## Caddy config (draft) ``` picortex.globalbr.ai { reverse_proxy 127.0.0.1:7823 } ``` ## Health checks - `https://picortex.globalbr.ai/health` returns `{status:"ok"}` - Journalctl `journalctl -u picortex -f` - `bd list --status=open` for blocker tickets ## Rollback `git reset --hard <previous-sha> && systemctl restart picortex`