docs(07-03): Deployment testing plan and documentation

scripts/build-check.sh

@@ -1,6 +1,25 @@
 #!/bin/bash
 # Compare deployed container versions against local git HEAD
 # Warns if containers are stale (built from an older commit)
+#
+# Usage:
+#   ./scripts/build-check.sh
+#
+# What it shows:
+#   - Local git HEAD commit SHA
+#   - Each container's built commit SHA (from Docker labels)
+#   - Whether containers are up-to-date or stale
+#   - Warnings if labels are missing (pre-07-02 containers)
+#
+# Label fields read:
+#   - org.opencontainers.image.revision = Git commit SHA embedded by deploy.sh
+#   - org.opencontainers.image.created = Build timestamp (ISO 8601 format)
+#
+# Exit codes:
+#   0 = All containers up to date
+#   1+ = Warnings or stale containers detected
+#
+# See: /docs/DEPLOYMENT.md for troubleshooting
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(dirname "$SCRIPT_DIR")"
@@ -11,14 +30,19 @@ LOCAL_COMMIT=$(git rev-parse HEAD)
 echo "Local HEAD: $(git rev-parse --short HEAD) ($LOCAL_COMMIT)"
 echo ""
 
+# Check a single container's build status
+# Args: $1 = container name
 check() {
   local name="$1"
 
+  # Container not running
   if ! docker inspect "$name" &>/dev/null; then
     echo "[$name] Not running"
     return
   fi
 
+  # Read Docker labels set by deploy.sh
+  # If labels are missing, container was built before phase 07-02
   local commit date
   commit=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' 2>/dev/null)
   date=$(docker inspect "$name" --format '{{index .Config.Labels "org.opencontainers.image.created"}}' 2>/dev/null)
@@ -28,8 +52,10 @@ check() {
     return
   fi
 
+  # Display container info
   echo "[$name] Built: ${commit:0:7} on ${date:-unknown}"
 
+  # Compare container commit to local HEAD
   if [ "$commit" = "$LOCAL_COMMIT" ]; then
     echo "[$name] OK: up to date"
   else
@@ -37,5 +63,6 @@ check() {
   fi
 }
 
+# Check both containers
 check "gravl-backend"
 check "gravl-frontend"

scripts/deploy.sh

@@ -1,6 +1,24 @@
 #!/bin/bash
 # Gravl deployment script
 # Prevents stale containers by always building fresh with --no-cache
+# 
+# Usage:
+#   ./scripts/deploy.sh
+#
+# What it does:
+#   1. Pulls latest code from git
+#   2. Captures build metadata (commit SHA, timestamp)
+#   3. Builds fresh Docker images with --no-cache (no layer caching)
+#   4. Restarts containers to use new images
+#   5. Polls /api/health endpoint until backend is ready
+#   6. Logs all steps to logs/deploy.log
+#
+# Rationale for --no-cache:
+#   Docker caching can hide stale assets (JS, CSS, images) when source files change.
+#   Using --no-cache ensures all layers rebuild fresh, guaranteeing new code is deployed.
+#   Trade-off: Slightly slower builds (30-60s vs 10-20s with cache), but safer.
+#
+# See: /docs/DEPLOYMENT.md for troubleshooting
 
 set -euo pipefail
 
@@ -18,25 +36,32 @@ cd "$REPO_DIR"
 
 log "=== Deploy started ==="
 
-# Pull latest code
+# Pull latest code from remote
+# Fails if there are local changes or merge conflicts
 log "Pulling latest code..."
 git pull
 
-# Capture build metadata
+# Capture build metadata to embed in Docker image labels
+# These labels allow build-check.sh to verify deployed containers match local code
 GIT_COMMIT=$(git rev-parse HEAD)
 BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 log "Commit: $(git rev-parse --short HEAD) | Date: $BUILD_DATE"
 
-# Build fresh images — no-cache prevents stale assets
+# Build fresh images — no-cache prevents Docker layer caching
+# This is critical for frontend deployments where CSS/JS changes might not be obvious
+# to Docker's layer detection algorithm
 log "Building images (--no-cache)..."
 export GIT_COMMIT BUILD_DATE
 docker compose build --no-cache
 
 # Restart containers with new images
+# --force-recreate stops old containers and removes them before starting new ones
 log "Starting containers..."
 docker compose up -d --force-recreate
 
-# Health check: wait up to 60s for backend
+# Health check: poll /api/health endpoint until it responds with 200 OK
+# Timeout: 60 seconds (12 retries × 5 seconds each)
+# This prevents deployment from completing if the backend is broken
 log "Health check..."
 for i in $(seq 1 12); do
   if curl -sf "$BACKEND_HEALTH" >/dev/null 2>&1; then