mac-os-launch-agent-update

Author: joonsoome

docs/MACOS_LAUNCHAGENT_EXAMPLE.md

@@ -9,42 +9,32 @@ Place at: `~/Library/LaunchAgents/com.embed-rerank.server.plist`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-  <key>Label</key>
-  <string>com.embed-rerank.server</string>
-
-  <!-- server-run.sh activates .venv and loads .env -->
-  <key>ProgramArguments</key>
-  <array>
-    <string>/bin/bash</string>
-    <string>-lc</string>
-    <string>/Users/USERNAME/embed-rerank/tools/server-run.sh</string>
-  </array>
-
-  <key>WorkingDirectory</key>
-  <string>/Users/USERNAME/embed-rerank</string>
-
-  <!-- Auto-restart if the process exits -->
-  <key>KeepAlive</key>
-  <true/>
-
-  <key>RunAtLoad</key>
-  <true/>
-
-  <!-- Default values (can be overridden via .env) -->
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>HOST</key><string>0.0.0.0</string>
-    <key>PORT</key><string>11436</string>
-    <!-- Add more variables if needed -->
-  </dict>
-
-  <key>StandardOutPath</key>
-  <string>/tmp/embed-rerank.log</string>
-  <key>StandardErrorPath</key>
-  <string>/tmp/embed-rerank.err</string>
+        <key>Label</key>
+        <string>com.embed-rerank.server</string>
+        <key>ProgramArguments</key>
+        <array>
+                <string>/bin/sh</string>
+                <string>/Users/username/embed-rerank/tools/server-launchd.sh</string>
+        </array>
+        <key>WorkingDirectory</key>
+        <string>/Users/username/embed-rerank</string>
+        <key>EnvironmentVariables</key>
+        <dict>
+                <key>HOST</key><string>0.0.0.0</string>
+                <key>PORT</key><string>11436</string>
+                <key>MODEL_NAME</key><string>mlx-community/Qwen3-Embedding-4B-4bit-DWQ</string>
+        </dict>
+        <key>KeepAlive</key>
+        <true/>
+        <key>RunAtLoad</key>
+        <true/>
+        <key>StandardOutPath</key>
+        <string>/tmp/embed-rerank.log</string>
+        <key>StandardErrorPath</key>
+        <string>/tmp/embed-rerank.err</string>
 </dict>
 </plist>
 ```
@@ -81,7 +71,4 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.embed-rerank.server.
 ## Notes
 - Ensure the path contains no typos (spaces are fine because we invoke via bash -lc).
 - `.venv` and `.env` must exist in the repo root.
-- For system-wide usage, create a LaunchDaemon under `/Library/LaunchDaemons/` (then adjust ownership/root requirements).
-```
-
-Similar code found with 1 license type
+- For system-wide usage, create a LaunchDaemon under `/Library/LaunchDaemons/` (then adjust ownership/root requirements).

tools/server-launchd.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# LaunchAgent-only startup script
+#  - launchd manages process lifecycle (restart / stdout & stderr redirection)
+#  - No backgrounding, nohup, PID files, or watchdog required here
+#  - Clear separation: server-run.sh (manual/dev, background + watchdog) vs server-launchd.sh (foreground for launchd)
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Provide sane locale defaults (launchd often supplies a minimal environment)
+export LANG="${LANG:-en_US.UTF-8}"
+export LC_ALL="${LC_ALL:-en_US.UTF-8}"
+
+# Prepend project virtualenv to PATH to ensure correct python & scripts are found first
+export PATH="$REPO_ROOT/.venv/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+
+VENV_PY="./.venv/bin/python"
+if [[ ! -x "$VENV_PY" ]]; then
+  echo "[launchd] .venv python not found. Create & install deps:\n  python -m venv .venv\n  . .venv/bin/activate\n  pip install -r requirements.txt" >&2
+  exit 2
+fi
+
+# Load .env (if present) to populate environment variables
+if [[ -f .env ]]; then
+  set -a
+  # shellcheck disable=SC1091
+  . .env
+  set +a
+fi
+
+HOST="${HOST:-0.0.0.0}"
+PORT="${PORT:-9000}"
+
+echo "[launchd] Starting embed-rerank (HOST=${HOST} PORT=${PORT}) using $($VENV_PY -V 2>/dev/null || echo python)"
+
+# Foreground exec so launchd can supervise the process directly
+exec "$VENV_PY" -m uvicorn app.main:app --host "$HOST" --port "$PORT"

tools/server-run-watchdog.sh

@@ -55,7 +55,9 @@ restart_server() {
   fi
   # Restart via server-run.sh but prevent spawning a second watchdog
   echo "[watchdog] Starting fresh server instance" | tee -a "$LOGFILE"
-  WATCHDOG_SKIP=1 bash "$REPO_ROOT/tools/server-run.sh" >> "$LOGFILE" 2>&1 || {
+  # Use bash -lc with a single argument so paths with spaces are handled
+  # correctly by the shell. This avoids splitting $REPO_ROOT on spaces.
+  WATCHDOG_SKIP=1 bash -lc "exec '$REPO_ROOT/tools/server-run.sh'" >> "$LOGFILE" 2>&1 || {
     echo "[watchdog] Restart attempt failed" | tee -a "$LOGFILE"
   }
 }

tools/server-run.sh

@@ -98,7 +98,9 @@ if [[ "${WATCHDOG_SKIP:-0}" != "1" && "$WATCHDOG" == "1" ]]; then
     echo "Watchdog already running (PID $(cat "$WATCHDOG_PIDFILE"))"
   else
     echo "Starting watchdog..." | tee -a "$LOGFILE"
-    nohup bash "$REPO_ROOT/tools/server-run-watchdog.sh" >> "$LOGFILE" 2>&1 &
+  # Execute watchdog script directly (ensure script is executable). Quoting the
+  # full path prevents word-splitting when REPO_ROOT contains spaces.
+  nohup "$REPO_ROOT/tools/server-run-watchdog.sh" >> "$LOGFILE" 2>&1 &
     if command -v disown >/dev/null 2>&1; then disown $! || true; fi
   fi
 fi