feat: add stack reset helper and setup runbook

CONTRIBUTING.md

@@ -81,6 +81,12 @@ Standard test deployment command:
 ./scripts/deploy_test_from_mac.sh
 ```
 
+Destructive fresh reset command:
+
+```bash
+RESET_CONFIRM=RESET EXPECTED_BRANCH=develop ./scripts/reset_stack_from_mac.sh
+```
+
 Why:
 - GitHub-hosted runners cannot reliably reach the private LAN target at `192.168.2.55`
 

DEPLOYMENT.md

@@ -217,6 +217,43 @@ HEALTH_URL=http://192.168.2.55:8088/healthz/ \
 ./scripts/deploy_test_from_mac.sh
 ```
 
+## Reset a stack from scratch
+Use this only when you intentionally want a fresh environment with default bootstrap data.
+
+What it does:
+1. syncs the current checkout to the target server
+2. stops the stack
+3. removes compose volumes with `down -v`
+4. rebuilds and bootstraps the stack again
+5. verifies the health endpoint
+
+Local test server reset:
+```bash
+git checkout develop
+RESET_CONFIRM=RESET EXPECTED_BRANCH=develop ./scripts/reset_stack_from_mac.sh
+```
+
+Customer/TUBCO reset example:
+```bash
+git checkout release/tubco-v1
+RESET_CONFIRM=RESET \
+EXPECTED_BRANCH=release/tubco-v1 \
+DEPLOY_HOST=root@<customer-host> \
+DEPLOY_PATH=/opt/workdock \
+REMOTE_ENV_FILE=.env.prod \
+HEALTH_URL=https://portal.tub.co/healthz/ \
+RUN_DJANGO_CHECK=1 \
+./scripts/reset_stack_from_mac.sh
+```
+
+This is destructive. It wipes:
+- database state
+- generated documents/media
+- staticfiles volume
+- backup volume
+
+It does not remove the server-local env file. That file must already exist.
+
 ## Manual production deployment
 For production, use a dedicated helper instead of the test script.
 

backend/workflows/templates/workflows/developer_handbook.html

@@ -684,6 +684,22 @@ docker compose restart worker</code></pre>
       <pre><code>./scripts/deploy_test_from_mac.sh</code></pre>
       <p>Sync the current <code>develop</code> checkout to the LAN test server and deploy it.</p>
     </div>
+    <div class="box">
+      <h3>Reset a stack from scratch</h3>
+      <pre><code>git checkout develop
+RESET_CONFIRM=RESET EXPECTED_BRANCH=develop ./scripts/reset_stack_from_mac.sh</code></pre>
+      <p>Wipe the current test stack state and rebuild it with default bootstrap data.</p>
+      <pre><code>git checkout release/tubco-v1
+RESET_CONFIRM=RESET \
+EXPECTED_BRANCH=release/tubco-v1 \
+DEPLOY_HOST=root@&lt;customer-host&gt; \
+DEPLOY_PATH=/opt/workdock \
+REMOTE_ENV_FILE=.env.prod \
+HEALTH_URL=https://portal.tub.co/healthz/ \
+RUN_DJANGO_CHECK=1 \
+./scripts/reset_stack_from_mac.sh</code></pre>
+      <p>Use the second form for a customer setup from scratch. This is destructive and removes database/media/static/backups before bootstrapping again.</p>
+    </div>
     <div class="box">
       <h3>Production deployment</h3>
       <pre><code>./scripts/deploy_prod_from_mac.sh</code></pre>

scripts/reset_stack_from_mac.sh

@@ -0,0 +1,82 @@
+#!/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}"
+EXPECTED_BRANCH="${EXPECTED_BRANCH:-}"
+RESET_CONFIRM="${RESET_CONFIRM:-}"
+
+cd "$REPO_ROOT"
+
+current_branch="$(git branch --show-current)"
+
+if [[ -n "$EXPECTED_BRANCH" && "$current_branch" != "$EXPECTED_BRANCH" ]]; then
+  echo "Expected branch '$EXPECTED_BRANCH' for this reset, got '$current_branch'." >&2
+  exit 1
+fi
+
+if [[ "$RESET_CONFIRM" != "RESET" ]]; then
+  cat >&2 <<EOF
+Refusing destructive reset.
+
+This command wipes the stack state for:
+  $DEPLOY_HOST:$DEPLOY_PATH
+
+It will remove:
+  - database volume/data
+  - generated media
+  - staticfiles volume
+  - backup volume
+
+Run again with:
+  RESET_CONFIRM=RESET ./scripts/reset_stack_from_mac.sh
+EOF
+  exit 1
+fi
+
+echo "Current branch: $current_branch"
+echo "Updating local branch from origin/$current_branch ..."
+git pull --ff-only origin "$current_branch"
+
+echo "Checking remote env file..."
+$SSH_CMD "$DEPLOY_HOST" "test -f '$DEPLOY_PATH/$REMOTE_ENV_FILE'" || {
+  echo "Missing remote env file: $DEPLOY_PATH/$REMOTE_ENV_FILE" >&2
+  echo "Create or restore the server env file before resetting." >&2
+  exit 1
+}
+
+echo "Syncing repository to ${DEPLOY_HOST}:${DEPLOY_PATH} ..."
+rsync -az --delete \
+  --filter 'P .env.test' \
+  --filter 'P .env.prod' \
+  --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 "Resetting remote stack state..."
+$SSH_CMD "$DEPLOY_HOST" "cd '$DEPLOY_PATH' && export APP_ENV_FILE='$REMOTE_ENV_FILE' && docker compose --env-file '$REMOTE_ENV_FILE' -f '$COMPOSE_FILE' down -v"
+
+echo "Rebuilding and bootstrapping fresh stack..."
+$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
+commit_sha="$(git rev-parse --short HEAD)"
+echo "Reset deployment healthy: $HEALTH_URL"
+echo "Deployed commit: $commit_sha"
+echo "Branch: $current_branch"