feat: add local test deployment helper

DEPLOYMENT.md

@@ -161,7 +161,37 @@ And a real HTTPS hostname in:
 - `SITE_ADDRESS`
 
 ## Manual test deployment
-If you need to deploy manually on the test server:
+For a LAN-only test server, this is the recommended CD path.
+
+### One-command local deployment from your Mac
+Use:
+```bash
+./scripts/deploy_test_from_mac.sh
+```
+
+What it does:
+1. requires the current branch to be `develop`
+2. fast-forwards from `origin/develop`
+3. syncs the repo to `/opt/workdock` via `rsync`
+4. runs the remote deployment script
+5. verifies the health endpoint
+
+Default assumptions:
+- target host: `root@192.168.2.55`
+- target path: `/opt/workdock`
+- env file: `.env.test`
+- health URL: `http://192.168.2.55:8088/healthz/`
+
+Optional overrides:
+```bash
+DEPLOY_HOST=root@192.168.2.55 \
+DEPLOY_PATH=/opt/workdock \
+HEALTH_URL=http://192.168.2.55:8088/healthz/ \
+./scripts/deploy_test_from_mac.sh
+```
+
+### Manual server-side deploy only
+If the latest code is already on the server:
 ```bash
 cd /opt/workdock
 RUN_DJANGO_CHECK=0 DEPLOY_HEALTH_URL="http://127.0.0.1:8088/healthz/" ./scripts/deploy_stack.sh .env.test docker-compose.prod.yml
@@ -185,6 +215,11 @@ Behavior:
 - uploads the working tree to the server over SSH
 - runs the server deployment script
 
+Important:
+- this workflow only works if the GitHub runner can reach the server
+- it is not suitable for a pure LAN-only target using a private IP like `192.168.2.55`
+- for the current environment, prefer the local Mac deploy script or a self-hosted runner on the LAN
+
 ### Production deployment workflow
 File:
 - [deploy-prod.yml](/Users/bostame/Documents/workdock-platform/.github/workflows/deploy-prod.yml)

backend/workflows/templates/workflows/developer_handbook.html

@@ -294,6 +294,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
       <li>Current production workflow file: <code>.github/workflows/deploy-prod.yml</code>.</li>
       <li>GitHub Actions uploads the working tree to the server over SSH. The server does not clone from GitHub.</li>
       <li>This is intentional for a private repository: it removes the need to store GitHub deploy keys on the target server.</li>
+      <li>However, GitHub-hosted runners cannot reach a LAN-only private IP like <code>192.168.2.55</code>. For the current local test server, the correct CD path is manual deployment from a LAN machine or a self-hosted runner inside the same network.</li>
     </ul>
     <h3>GitHub Environments</h3>
     <ul>
@@ -382,6 +383,10 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
       <li>Wait until <code>/healthz/</code> becomes healthy</li>
     </ol>
     <h3>Manual deploy</h3>
+    <p>The preferred current test-deployment path is the local helper script from a Mac or another LAN-connected workstation:</p>
+    <pre><code>./scripts/deploy_test_from_mac.sh</code></pre>
+    <p>This script fast-forwards <code>develop</code>, syncs the repo to the server with <code>rsync</code>, runs the remote deployment, and verifies the health endpoint.</p>
+    <p>Direct server-side deploy is still available if the code is already on the server:</p>
     <pre><code>cd /opt/workdock
 RUN_DJANGO_CHECK=0 DEPLOY_HEALTH_URL="http://127.0.0.1:8088/healthz/" ./scripts/deploy_stack.sh .env.test docker-compose.prod.yml</code></pre>
     <h3>Validation after deploy</h3>

scripts/deploy_test_from_mac.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DEPLOY_HOST="${DEPLOY_HOST:-root@192.168.2.55}"
+DEPLOY_PATH="${DEPLOY_PATH:-/opt/workdock}"
+HEALTH_URL="${HEALTH_URL:-http://192.168.2.55:8088/healthz/}"
+REMOTE_ENV_FILE="${REMOTE_ENV_FILE:-.env.test}"
+COMPOSE_FILE="${COMPOSE_FILE:-docker-compose.prod.yml}"
+RUN_DJANGO_CHECK="${RUN_DJANGO_CHECK:-0}"
+SSH_CMD="${SSH_CMD:-ssh -4}"
+RSYNC_SSH="${RSYNC_SSH:-ssh -4}"
+
+cd "$REPO_ROOT"
+
+current_branch="$(git branch --show-current)"
+if [[ "$current_branch" != "develop" ]]; then
+  echo "Expected branch 'develop' for test deployment, got '$current_branch'." >&2
+  echo "Switch to develop or override intentionally before deploying." >&2
+  exit 1
+fi
+
+echo "Updating local branch from origin/develop..."
+git pull --ff-only origin develop
+
+echo "Syncing repository to ${DEPLOY_HOST}:${DEPLOY_PATH} ..."
+rsync -az --delete \
+  --exclude '.git' \
+  --exclude '.github' \
+  --exclude '.venv' \
+  --exclude '__pycache__' \
+  --exclude 'node_modules' \
+  --exclude 'backend/media' \
+  --exclude 'backend/staticfiles' \
+  -e "$RSYNC_SSH" \
+  "$REPO_ROOT"/ \
+  "${DEPLOY_HOST}:${DEPLOY_PATH}/"
+
+echo "Running remote deployment..."
+$SSH_CMD "$DEPLOY_HOST" \
+  "cd '$DEPLOY_PATH' && RUN_DJANGO_CHECK='$RUN_DJANGO_CHECK' DEPLOY_HEALTH_URL='$HEALTH_URL' ./scripts/deploy_stack.sh '$REMOTE_ENV_FILE' '$COMPOSE_FILE'"
+
+echo "Verifying health endpoint..."
+curl --fail --silent --show-error --max-time 10 "$HEALTH_URL" >/dev/null
+echo "Test deployment healthy: $HEALTH_URL"