Clarify Docker-first deploy workflow
Updated deploy messaging and deployment docs so Docker is clearly the supported VPS path today, while the native runtime is labeled experimental and fails faster with clearer prerequisites.
Summary
The deploy helper now warns when --runtime native is used, defaults native systemctl invocations to sudo -n systemctl so they fail fast instead of hanging for a password, and prints explicit precheck errors when Bun or systemd readiness is missing. Docs now describe Docker as the default and recommended VPS rollout path.
Changes Made
- Updated
scripts/deploy.tshelp text to mark Docker as default and recommended, and native as experimental. - Changed the native systemctl default from
sudo systemctltosudo -n systemctlto avoid interactive hangs. - Added a runtime advisory banner for native deploy attempts.
- Improved native remote precheck failures for missing Bun, missing systemctl access, and missing systemd units.
- Updated
README.md,deployment/docker/README.md, anddeployment/native/README.mdto reflect the live VPS reality: Docker plus Nginx Proxy Manager remains the supported deployment path.
Context
Live inspection of the VPS showed that Nginx Proxy Manager routes flow.deltaisland.io and API traffic to the Docker web and api containers by container name on the shared Docker network. The host does not currently have Bun installed, passwordless sudo systemctl is not configured, and no Islandflow systemd units are present. Because of that, native deployment should be treated as future infrastructure work rather than the recommended day-to-day path.
Important Implementation Details
- Native rollout prechecks now fail with actionable messages instead of a silent command failure or a hanging sudo prompt.
- The native docs now explicitly say the current VPS is not prepared for routine native rollouts.
- Docker deployment behavior itself was not changed. This was a clarity and guardrail pass, not a runtime migration.
[deploy] Native runtime is experimental. Use --runtime docker for the current supported VPS path unless Bun, systemd units, and proxy routing have been prepared intentionally.
Validation
- Passed:
./deploy --help - Passed:
bun run check:docker-workspace - Passed:
./deploy main --runtime native --no-buildnow fails quickly with an explicit Bun-missing message on the live VPS
./deploy --help ./deploy main --runtime native --no-build bun run check:docker-workspace
Issues, Limitations, and Mitigations
- Native deploy remains experimental. Mitigation: docs and CLI output now say so directly.
- The live VPS still depends on Docker-name routing through Nginx Proxy Manager. Mitigation: Docker remains the recommended deployment path.
- No systemd units or Bun install were added in this change. That work remains a separate follow-up.
Follow-up Work
- Keep native deployment support available for future experimentation, but treat it as opt-in infrastructure work.
- Open follow-up:
islandflow-38p, add native deployment unit templates and rollback helpers if the host-native path is revived later.