Turn document · 2026-05-18 03:29 EDT · Issues: islandflow-9rc, islandflow-38p, islandflow-bsg, islandflow-2db

# Native fast iterative deploy

Implemented the native-first iterative deploy plan by adding deploy timing output, a safe worker-only native fast path, checked-in systemd user units and rollback helpers, server-local deploy execution, and updated live-operational documentation based on a fresh VPS audit.

## Summary

The deploy flow now supports a safer native worker iteration model without requiring public edge cutover first. It can run directly from the VPS checkout without SSH, emits phase timings, includes checked-in native unit files plus install/rollback/smoke-test helpers, and documents the staged cutover path. During live audit, the previously reported `/replay/options` proxy issue and duplicate `islandflow` compose stack were both confirmed resolved on the host.

## Changes Made

- Extended `scripts/deploy.ts` with deploy timing summaries for precheck, rollout, and verification phases.
- Added `--workers-only` deploy scope for Docker and native runtimes.
- Changed native `--fast` behavior so default full-scope fast deploys become worker-only instead of touching web/API.
- Added native edge guardrails via `DEPLOY_NATIVE_EDGE_READY=1` before web/API native deploys are allowed.
- Added local-server execution mode so `./deploy` can run from `/home/delta/islandflow` without SSHing back into the same host.
- Added `DEPLOY_SSH_KEY_PATH` and `DEPLOY_FORCE_SSH` overrides for operators with non-default SSH setups.
- Checked in native ops assets under `deployment/native/`:
- `install-user-units.sh`, `check-native-health.sh`, `rollback.sh`
- six user unit files in `deployment/native/systemd/user/`
- Updated `README.md`, `deployment/docker/README.md`, and `deployment/native/README.md` to document the worker-first model, local execution mode, validation matrix, and staged cutover guidance.
- Synced `deployment/docker/workspace-root/package.json` so Docker workspace validation passes again.
- Installed the checked-in user unit files onto the live VPS in disabled form under `~/.config/systemd/user`.

## Context

The plan targeted faster deployment iteration while avoiding a premature move of the public edge away from the current Docker + Nginx Proxy Manager topology. The practical target was to make native runtime useful immediately for backend-worker iteration, while leaving web/API cutover deliberate and reversible.

## Important Implementation Details

- Native fast mode now defaults to `--workers-only`; Docker fast mode still defaults to `--services-only`.
- Native deploys that include public web/API scope now fail fast unless `DEPLOY_NATIVE_EDGE_READY=1` is set.
- Running from the live VPS checkout automatically switches deploy execution from SSH mode to local mode.
- The checked-in native unit files are user units aimed at the current VPS layout: `/home/delta/islandflow` and `/home/delta/.bun/bin/bun`.
- `install-user-units.sh` now installs units safely without enabling anything by default; enabling is explicit and scope-based.
- `rollback.sh` intentionally uses a detached git ref to make one-off native rollback practical without rewriting branch history.

    export DEPLOY_NATIVE_SYSTEMCTL_PREFIX="systemctl --user"
    ./deploy main --runtime native --fast
    # resolves to worker-only native deploy before public edge cutover

## Expected Impact for End-Users

End-users should see indirect benefits first: faster backend iteration, safer operational changes, and clearer rollback paths. Public traffic behavior should remain unchanged until a deliberate native edge cutover is performed.

## Validation

- Passed: `bun run scripts/check-public-api-routes.ts https://flow.deltaisland.io`
- Passed: direct public `/replay/options` curl returned JSON
- Passed: live Nginx Proxy Manager config contains `/replay` in the API route matcher
- Passed: `docker compose ls` shows no duplicate `islandflow` project
- Passed: `bash -n deployment/native/install-user-units.sh deployment/native/check-native-health.sh deployment/native/rollback.sh`
- Passed: `systemd-analyze verify deployment/native/systemd/user/*.service`
- Passed: `bun run check:docker-workspace` after syncing workspace snapshot
- Passed: native edge guard refusal for `bun run scripts/deploy.ts main --runtime native --web-only --no-build`
- Passed: `./deployment/native/install-user-units.sh` followed by `systemctl --user list-unit-files 'islandflow*'`

## Issues, Limitations, and Mitigations

- Native units were installed but not enabled or started. This is intentional to avoid conflicting with the current Docker production edge.
- Public web/API native deploys are still gated. Mitigation: explicit `DEPLOY_NATIVE_EDGE_READY=1` acknowledgment and staged cutover documentation.
- Native worker runtime has not yet been exercised live against the existing Docker worker stack. Mitigation: follow-up issue to soak worker-only native units before any default-runtime decision.
- The known untracked Signal CLI tarball remains in the repo checkout. This is already tolerated by the deploy helper allowlist and was not changed here.

## Follow-up Work

- Open follow-up: `islandflow-vvw` — stage native public-edge cutover after worker soak.
- Decide whether native should ever replace Docker as the default runtime only after worker soak data and deliberate edge cutover validation.