Add dual-runtime deploy workflow

deployment/native/README.md

@@ -0,0 +1,122 @@
+# Native Deployment
+
+This directory documents the host-native Islandflow rollout path used by:
+
+```bash
+./deploy main --runtime native
+./deploy current-branch --runtime native
+```
+
+This runtime is intended for faster server iteration during the transition away from Docker-only app rollouts. Local development should still prefer:
+
+- Docker for infra (`bun run dev:infra`)
+- native Bun services (`bun run dev:services`)
+- native Next.js web (`bun run dev:web`)
+
+## What native deploy means here
+
+The checked-in `deploy` helper assumes:
+
+- the live repo checkout is still `/home/delta/islandflow`
+- Bun is installed on the VPS
+- app processes are managed by `systemd`
+- infrastructure services such as NATS, ClickHouse, and Redis are already reachable from the host
+- the web app runs from `apps/web` and is served with `next start -p 3000`
+
+The deploy script updates the repo checkout, optionally runs `bun install --frozen-lockfile`, optionally rebuilds the web app, restarts the target systemd units, and then verifies the services locally on the VPS plus through the public app URL.
+
+## Expected unit names
+
+Default unit names used by `scripts/deploy.ts`:
+
+- `islandflow-web`
+- `islandflow-api`
+- `islandflow-compute`
+- `islandflow-candles`
+- `islandflow-ingest-options`
+- `islandflow-ingest-equities`
+
+Override them from your local shell before running `./deploy` if the server uses different names:
+
+```bash
+export DEPLOY_NATIVE_WEB_UNIT=my-web-unit
+export DEPLOY_NATIVE_API_UNIT=my-api-unit
+```
+
+Available overrides:
+
+- `DEPLOY_NATIVE_WEB_UNIT`
+- `DEPLOY_NATIVE_API_UNIT`
+- `DEPLOY_NATIVE_COMPUTE_UNIT`
+- `DEPLOY_NATIVE_CANDLES_UNIT`
+- `DEPLOY_NATIVE_INGEST_OPTIONS_UNIT`
+- `DEPLOY_NATIVE_INGEST_EQUITIES_UNIT`
+
+## systemctl invocation
+
+By default the deploy helper uses:
+
+```bash
+sudo systemctl
+```
+
+If the server uses user units or another wrapper, override it locally before invoking `./deploy`:
+
+```bash
+export DEPLOY_NATIVE_SYSTEMCTL_PREFIX="systemctl --user"
+./deploy main --runtime native
+```
+
+## Partial native rollouts
+
+Examples:
+
+```bash
+./deploy main --runtime native --web-only
+./deploy main --runtime native --api-only
+./deploy current-branch --runtime native --services-only
+./deploy main --runtime native --web-only --no-build
+```
+
+Scope behavior:
+
+- default: restart web + API + backend services
+- `--web-only`: rebuild/restart only the web unit
+- `--api-only`: restart only the API unit
+- `--services-only`: restart API + backend units without touching the web unit
+- `--no-build`: skip `bun install --frozen-lockfile` and skip the web build step
+
+## Server preparation checklist
+
+Before the first native rollout, ensure the VPS has:
+
+1. Bun installed and on `PATH`
+2. a working `/home/delta/islandflow/.env` (or unit-managed equivalent env source)
+3. systemd units for each target service
+4. the web unit configured to serve the built app on port `3000`
+5. the API unit configured to serve health checks on port `4000`
+6. infrastructure endpoints configured so the native services can reach NATS, ClickHouse, and Redis
+
+## Verification
+
+Native deploys verify:
+
+- target units are active via `systemctl`
+- recent unit status and journal output can be collected
+- local `http://127.0.0.1:4000/health` when API scope is included
+- local `http://127.0.0.1:3000/` when web scope is included
+- the public app URL from the local machine after the rollout finishes
+
+## Rollback
+
+Rollback remains manual for now:
+
+1. switch the server checkout back to the last known-good branch or commit
+2. rerun the appropriate native deploy command
+3. if needed, restart only the affected units with `systemctl`
+
+Docker remains available as the fallback runtime during the transition:
+
+```bash
+./deploy main --runtime docker
+```