Turn document 2026-05-15 Issue: islandflow-4gj

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

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

[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

./deploy --help
./deploy main --runtime native --no-build
bun run check:docker-workspace

Issues, Limitations, and Mitigations

Follow-up Work