# Evo auto-deploy (evOo-local)

Idempotent deploy helper for the **source checkout** on the Evo host (`~/Projects/evOo-local`, user `cynar`). Pulls `main` (or a pinned SHA), runs migrations, restarts the existing stack, health-checks API `:3100` and web `:5173`, and rolls back on failure.

This is separate from production Docker deploys under `/srv/rakazo` (see `docs/self-host.md` and `.github/workflows/ci.yml` `deploy-production`).

## Prerequisites on Evo

1. Git checkout at `~/Projects/evOo-local` (or set `EVO_DEPLOY_DIR`).
2. `.env` with a working `DATABASE_URL` (Postgres reachable for `pnpm db:migrate`).
3. A restart path the script can use (pick one):
   - **systemd (recommended for unattended deploy):** user unit, e.g. `evoo-local.service`, that starts `pnpm dev` or your stack wrapper. Set repo variable `EVO_SYSTEMD_UNIT`.
   - **tmux:** session `evoo` running `pnpm dev` (matches `scripts/start-tmux.sh` on Mac; on Evo set `EVO_TMUX_SESSION` if different).
   - **compose:** `infra/compose/docker-compose.yml` with `api` / `web` / `worker` (dev stack).
   - **script:** executable hook at `EVO_RESTART_SCRIPT`.
4. Self-hosted GitHub Actions runner on Evo with labels `[self-hosted, evoo-ci, Linux]` (already used by CI).

No SSH keys or deploy secrets are stored in this repo. The workflow runs **on** the Evo runner against the local checkout.

## Enable the workflow

1. Merge this PR (or copy `ops/evo-deploy/` and `.github/workflows/evo-deploy.yml` to `main`).
2. In GitHub → **Settings → Secrets and variables → Actions → Variables** for `cynarAI/evOo-local`:
   - `EVO_DEPLOY_ENABLED` = `true`
   - Optional: `EVO_DEPLOY_DIR` (default `~/Projects/evOo-local` on the runner user)
   - Optional: `EVO_RESTART_MODE` (`auto`, `systemd`, `tmux`, `compose`, `script`, `none`)
   - Optional: `EVO_SYSTEMD_UNIT`, `EVO_TMUX_SESSION`, health URLs, timeouts
3. Confirm the runner user can read/write `EVO_DEPLOY_DIR` and restart services (`systemctl --user` or tmux).

Until `EVO_DEPLOY_ENABLED` is `true`, pushes to `main` do not deploy (workflow job is skipped).

## Manual / dry-run

On Evo (or any machine with the checkout and stack):

```bash
cd ~/Projects/evOo-local

# Show what would happen (no git reset, migrate, restart, or health wait)
bash ops/evo-deploy/deploy.sh --dry-run

# Deploy main tip
bash ops/evo-deploy/deploy.sh

# Pin a SHA
EVO_DEPLOY_REF=abc1234 bash ops/evo-deploy/deploy.sh

# Force systemd restart
EVO_RESTART_MODE=systemd EVO_SYSTEMD_UNIT=evoo-local.service bash ops/evo-deploy/deploy.sh
```

GitHub: **Actions → evo-deploy → Run workflow** (optional `ref`, `dry_run`, `skip_migrate`).

## Rollback behavior

1. Before `git fetch`, the script records `previousSha` (current `HEAD`).
2. After pull, migrate, and restart, it waits up to `EVO_HEALTH_TIMEOUT_SEC` (default 120s) for:
   - `EVO_API_HEALTH_URL` (default `http://127.0.0.1:3100/health`)
   - `EVO_WEB_HEALTH_URL` (default `http://127.0.0.1:5173/`)
3. On failure: `git reset --hard` to `previousSha`, restart services again, exit non-zero.
4. Last outcome is written to `.evo-deploy/state.json` under the checkout.

Manual rollback to a known good SHA:

```bash
cd ~/Projects/evOo-local
git reset --hard <good-sha>
EVO_RESTART_MODE=systemd EVO_SYSTEMD_UNIT=evoo-local.service bash ops/evo-deploy/deploy.sh --skip-migrate --ref HEAD
```

(or restart your unit/tmux session by hand, then verify health URLs).

## Autopilot / Grok Bot after merge

After a PR merges to `main`:

1. **Preferred:** rely on the `evo-deploy` workflow (once `EVO_DEPLOY_ENABLED=true`). No SSH step required.
2. **Fallback (manual):** SSH to Evo and run:
   ```bash
   cd ~/Projects/evOo-local && bash ops/evo-deploy/deploy.sh
   ```
3. **Verify:** API `curl -fsS http://127.0.0.1:3100/health`, web `curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5173/`.

Do not commit host passwords, tokens, or SSH private keys. Configure restart targets via repo variables or env on the runner host only.

## Environment reference

| Variable | Default | Purpose |
|----------|---------|---------|
| `EVO_DEPLOY_DIR` | `$HOME/Projects/evOo-local` | Git checkout root |
| `EVO_DEPLOY_REF` | `main` | Branch name or commit SHA |
| `EVO_RESTART_MODE` | `auto` | `systemd` / `tmux` / `compose` / `script` / `none` |
| `EVO_SYSTEMD_UNIT` | _(empty)_ | Required for `systemd` mode |
| `EVO_SYSTEMD_SCOPE` | `user` | `user` or `system` |
| `EVO_TMUX_SESSION` | `evoo` | tmux session name |
| `EVO_TMUX_COMMAND` | `pnpm dev` | Command started in new tmux session |
| `EVO_MIGRATE` | `true` | Run `pnpm db:generate` + `pnpm db:migrate` |
| `EVO_INSTALL` | `true` | Run `pnpm install --frozen-lockfile` after checkout |
| `EVO_API_HEALTH_URL` | `http://127.0.0.1:3100/health` | API health probe |
| `EVO_WEB_HEALTH_URL` | `http://127.0.0.1:5173/` | Web health probe |
| `EVO_HEALTH_TIMEOUT_SEC` | `120` | Per-check timeout (seconds) |

If `EVO_RESTART_MODE=auto` cannot detect systemd, tmux, compose, or a restart script, deploy fails with a clear error — set `EVO_RESTART_MODE` and the matching unit/session explicitly.