phase: 02-operations-maintenance
plan: "03"
subsystem: deploy
tags: [cross-platform, bash, deploy, macOS, Linux]
dependency_graph:
requires: []
provides: [cross-platform-deploy]
affects: [deploy_rkl.sh]
tech_stack:
added: []
patterns: [OS detection via uname, platform-adaptive helper functions, configurable env vars]
key_files:
created: []
modified: [deploy_rkl.sh]
decisions:
- "pg_cmd() abstraction chosen over inline if/else at each psql call site — DRY, readable"
- "VENV_PIP configurable via env var with clear error message — zero config for standard Linux, flexible for macOS"
- "macOS svc_restart() warns instead of failing — on macOS dev setups services are managed differently"
metrics:
duration_minutes: 5
completed_date: "2026-03-24"
tasks_completed: 1
files_modified: 1

Phase 02 Plan 03: Cross-Platform deploy_rkl.sh Summary

One-liner: Added OS detection via uname -s and four platform-adaptive helper functions (pg_cmd, svc_restart, svc_active, nginx_reload) that replace all Linux-only calls in deploy_rkl.sh, making it work on both macOS and Linux without manual edits.

What Was Built

deploy_rkl.sh was previously Linux/systemd-only. It used sudo -u postgres psql, systemctl, journalctl, and hardcoded /etc/nginx/sites-available paths. These were incompatible with macOS development environments.

The script now:

  1. Detects the OS via uname -s at startup and sets $PLATFORM to macos or linux. Unsupported platforms exit immediately with an error message.

  2. Provides helper functions that branch on $PLATFORM:

  3. pg_cmd() — runs sudo -u postgres psql on Linux, plain psql on macOS
  4. svc_restart() — runs systemctl restart on Linux, warns to restart manually on macOS
  5. svc_active() — runs systemctl is-active on Linux, uses pgrep on macOS

  6. nginx_reload() — uses systemctl reload nginx on Linux, nginx -s reload on macOS

  7. Uses $NGINX_SITES variable set to /etc/nginx/sites-available on Linux or /opt/homebrew/etc/nginx/servers on macOS. The symlink step (sites-enabled) is Linux-only.

  8. Makes VENV_PIP configurable via environment variable with fallback to /opt/crumbforest/venv/bin/pip, with a clear warning when the path doesn't exist.

  9. Conditionalizes journalctl — on macOS, prints a manual instruction instead.

Tasks

Task Name Commit Files
1 Add OS detection and platform-adaptive commands 4dc8666 deploy_rkl.sh

Deviations from Plan

None — plan executed exactly as written.

Known Stubs

None — all platform branches are functional. macOS svc_restart intentionally warns instead of acting (no systemd on macOS; developer is expected to manage the process differently).

Self-Check: PASSED

  • deploy_rkl.sh exists: FOUND
  • Commit 4dc8666 exists: FOUND
  • bash -n deploy_rkl.sh: PASSED
  • grep uname: FOUND
  • grep PLATFORM: FOUND
  • grep Darwin: FOUND
  • grep Linux: FOUND
  • grep pg_cmd: FOUND