Wire maintenance page into deploy script as a dynamic toggle

Replaces the earlier auto-fallback-on-upstream-error approach with an
explicit flag-file toggle controlled by the deploy script. The flag
is touched before stopping the app and removed on successful finish
(or via trap if the deploy aborts), so a failed deploy doesn't strand
the site in maintenance.

- nginx/goodwalk.co.nz.svelte.conf.example: error_page 503 routes to
  /maintenance.html (internal); /m/ serves static maintenance assets;
  the / and /api/submit blocks return 503 when /etc/nginx/conf.d/
  maintenance.flag exists.
- nginx/maintenance.html: brand-styled "Be right back" page — full
  Goodwalk green background, white card with yellow accent, real
  Goodwalk logo, contact details fallback, auto-reload after 60s.
- nginx/logo.png: maintenance-time logo (served from /m/logo.png).
- nginx/nginx.conf: reverted the earlier auto-fallback edits; this
  file is not deployed (the prod conf is goodwalk.co.nz.svelte.conf
  .example).
- scripts/deploy-remote.sh: copies maintenance.html + logo into the
  nginx container, reloads nginx so the new conf is live, touches
  the flag, then runs the rebuild, then clears the flag. Adds a
  trap-based clear_maintenance_flag fallback. Also adds a defensive
  env-file merger that appends new keys from deploy.env.template
  without clobbering live values, with a timestamped .env backup.

Plus a small a11y polish unrelated to maintenance:
- ServicesSection: "Learn more" links now include screen-reader-only
  "about <Service>" context.
- base.css: adds .visually-hidden utility class.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

nginx/goodwalk.co.nz.svelte.conf.example

@@ -53,6 +53,26 @@ server {
     # nginx does not keep stale upstream IPs in memory.
     resolver 127.0.0.11 ipv6=off valid=30s;
 
+    # Maintenance mode: when /etc/nginx/conf.d/maintenance.flag exists,
+    # serve the static "be right back" page with a 503 status. The flag is
+    # toggled by the deploy script (touch / rm) without reloading nginx.
+    error_page 503 /maintenance.html;
+
+    location = /maintenance.html {
+        root /var/www/html;
+        internal;
+        add_header Cache-Control "no-store" always;
+    }
+
+    # Static assets used only by the maintenance page (logo, etc.). Served
+    # directly from the nginx html mount so they remain reachable while the
+    # SvelteKit app is down.
+    location /m/ {
+        root /var/www/html;
+        access_log off;
+        add_header Cache-Control "public, max-age=3600" always;
+    }
+
     location ~* /\.(git|env|htaccess) {
         deny all;
     }
@@ -66,6 +86,10 @@ server {
     }
 
     location /api/submit {
+        if (-f /etc/nginx/conf.d/maintenance.flag) {
+            return 503;
+        }
+
         set $goodwalk_mail_api goodwalk_svelte_mail_api:8000;
         limit_req zone=goodwalk_limit burst=10 nodelay;
         proxy_pass http://$goodwalk_mail_api/submit;
@@ -77,6 +101,10 @@ server {
     }
 
     location / {
+        if (-f /etc/nginx/conf.d/maintenance.flag) {
+            return 503;
+        }
+
         set $goodwalk_frontend goodwalk_svelte_app:3000;
         proxy_pass http://$goodwalk_frontend;
         proxy_http_version 1.1;

nginx/maintenance.html

@@ -8,8 +8,8 @@
     <style>
       :root {
         --green: #213021;
-        --yellow: #FFD100;
+        --green-soft: #2c3f2c;
-        --cream: #fbfaf6;
+        --yellow: #ffd100;
         --ink: #1a1a1a;
         --muted: #4c5056;
       }
@@ -28,7 +28,10 @@
       body {
         font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
         color: var(--ink);
-        background: var(--cream);
+        background:
+          radial-gradient(circle at top left, rgba(255, 209, 0, 0.12), transparent 55%),
+          radial-gradient(circle at bottom right, rgba(255, 209, 0, 0.08), transparent 60%),
+          var(--green);
         min-height: 100vh;
         display: grid;
         place-items: center;
@@ -36,14 +39,31 @@
         line-height: 1.5;
       }
 
+      .stage {
+        width: 100%;
+        max-width: 560px;
+      }
+
+      .brand-bar {
+        display: flex;
+        justify-content: center;
+        margin-bottom: 28px;
+      }
+
+      .brand-bar img {
+        display: block;
+        height: 44px;
+        width: auto;
+        max-width: 100%;
+        filter: brightness(0) invert(1);
+      }
+
       .card {
         position: relative;
-        max-width: 520px;
-        width: 100%;
         background: #fff;
         border-radius: 28px;
-        padding: 44px 40px 40px;
+        padding: 44px 40px 38px;
-        box-shadow: 0 18px 44px rgba(17, 20, 24, 0.08);
+        box-shadow: 0 24px 60px rgba(0, 0, 0, 0.25);
         text-align: center;
         overflow: hidden;
       }
@@ -62,7 +82,7 @@
         justify-content: center;
         width: 64px;
         height: 64px;
-        margin: 0 auto 20px;
+        margin: 4px auto 18px;
         border-radius: 50%;
         background: rgba(33, 48, 33, 0.08);
         color: var(--green);
@@ -73,13 +93,13 @@
         height: 32px;
       }
 
-      .brand {
+      .eyebrow {
-        font-size: 13px;
+        font-size: 12px;
         font-weight: 700;
         letter-spacing: 0.18em;
         text-transform: uppercase;
         color: var(--green);
-        margin: 0 0 14px;
+        margin: 0 0 10px;
       }
 
       h1 {
@@ -97,7 +117,7 @@
       }
 
       .meta {
-        margin-top: 22px;
+        margin-top: 24px;
         padding-top: 22px;
         border-top: 1px solid rgba(17, 20, 24, 0.08);
         font-size: 14px;
@@ -106,7 +126,7 @@
 
       .meta a {
         color: var(--green);
-        font-weight: 600;
+        font-weight: 700;
         text-decoration: none;
       }
 
@@ -114,31 +134,50 @@
         text-decoration: underline;
       }
 
+      .footnote {
+        margin-top: 22px;
+        text-align: center;
+        font-size: 13px;
+        color: rgba(255, 255, 255, 0.7);
+      }
+
       @media (max-width: 480px) {
         .card {
           padding: 36px 24px 28px;
           border-radius: 22px;
         }
+
+        .brand-bar img {
+          height: 36px;
+        }
       }
     </style>
   </head>
   <body>
-    <main class="card" role="main">
+    <div class="stage">
-      <span class="paw" aria-hidden="true">
+      <div class="brand-bar">
-        <svg viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+        <img src="/m/logo.png" alt="Goodwalk" width="241" height="48" />
-          <path d="M7.5 10.5c1.1 0 2-1.3 2-3s-.9-3-2-3-2 1.3-2 3 .9 3 2 3Zm9 0c1.1 0 2-1.3 2-3s-.9-3-2-3-2 1.3-2 3 .9 3 2 3ZM4 13.5c1 0 1.8-1.1 1.8-2.5S5 8.5 4 8.5s-1.8 1.1-1.8 2.5S3 13.5 4 13.5Zm16 0c1 0 1.8-1.1 1.8-2.5S21 8.5 20 8.5s-1.8 1.1-1.8 2.5.8 2.5 1.8 2.5ZM12 13.5c-3.3 0-6 2.5-6 5.4 0 1.4 1.1 2.6 2.5 2.6 1 0 1.5-.4 2.2-.8.4-.2.8-.4 1.3-.4s.9.2 1.3.4c.7.4 1.2.8 2.2.8 1.4 0 2.5-1.2 2.5-2.6 0-2.9-2.7-5.4-6-5.4Z"/>
-        </svg>
-      </span>
-
-      <p class="brand">Goodwalk</p>
-      <h1>Be right back!</h1>
-      <p>We're updating the site — should only take a minute. Thanks for your patience.</p>
-
-      <div class="meta">
-        Need us now? Email <a href="mailto:info@goodwalk.co.nz">info@goodwalk.co.nz</a>
-        or call <a href="tel:+64226421011">(022) 642 1011</a>.
       </div>
-    </main>
+
+      <main class="card" role="main">
+        <span class="paw" aria-hidden="true">
+          <svg viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+            <path d="M7.5 10.5c1.1 0 2-1.3 2-3s-.9-3-2-3-2 1.3-2 3 .9 3 2 3Zm9 0c1.1 0 2-1.3 2-3s-.9-3-2-3-2 1.3-2 3 .9 3 2 3ZM4 13.5c1 0 1.8-1.1 1.8-2.5S5 8.5 4 8.5s-1.8 1.1-1.8 2.5S3 13.5 4 13.5Zm16 0c1 0 1.8-1.1 1.8-2.5S21 8.5 20 8.5s-1.8 1.1-1.8 2.5.8 2.5 1.8 2.5ZM12 13.5c-3.3 0-6 2.5-6 5.4 0 1.4 1.1 2.6 2.5 2.6 1 0 1.5-.4 2.2-.8.4-.2.8-.4 1.3-.4s.9.2 1.3.4c.7.4 1.2.8 2.2.8 1.4 0 2.5-1.2 2.5-2.6 0-2.9-2.7-5.4-6-5.4Z"/>
+          </svg>
+        </span>
+
+        <p class="eyebrow">Goodwalk</p>
+        <h1>Be right back!</h1>
+        <p>We're updating the site — should only take a minute. Thanks for your patience.</p>
+
+        <div class="meta">
+          Need us now? Email <a href="mailto:info@goodwalk.co.nz">info@goodwalk.co.nz</a>
+          or call <a href="tel:+64226421011">(022) 642 1011</a>.
+        </div>
+      </main>
+
+      <p class="footnote">Auckland Central dog walking · Tiny Gang pack walks · 1:1 walks · Puppy visits</p>
+    </div>
 
     <script>
       // Auto-recheck once a minute so visitors don't sit on this page forever.

nginx/nginx.conf

@@ -29,14 +29,6 @@ server {
   gzip on;
   gzip_types text/plain text/css application/javascript application/json image/svg+xml;
 
-  # Served when the SvelteKit upstream is unreachable (deploys, restarts).
-  # Mounted into the nginx container at /var/www/html/maintenance.html.
-  location = /maintenance.html {
-    root /var/www/html;
-    internal;
-    add_header Cache-Control "no-store" always;
-  }
-
   location /api/submit {
     proxy_pass http://mail-api:8000/submit;
     proxy_http_version 1.1;
@@ -44,10 +36,6 @@ server {
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
-
-    proxy_intercept_errors on;
-    proxy_connect_timeout 2s;
-    error_page 502 503 504 = /maintenance.html;
   }
 
   location / {
@@ -59,13 +47,5 @@ server {
     proxy_set_header X-Forwarded-Proto $scheme;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection "upgrade";
-
-    # Serve a static maintenance page when the app container is down/restarting,
-    # rather than nginx's default 502/503. The `=` keeps the original status
-    # code so search engines treat it as a transient outage, not a real page.
-    proxy_intercept_errors on;
-    proxy_connect_timeout 2s;
-    proxy_next_upstream error timeout http_502 http_503 http_504;
-    error_page 502 503 504 = /maintenance.html;
   }
 }

scripts/deploy-remote.sh

@@ -114,8 +114,19 @@ else
 fi
 
 STAGING_DIR="$(mktemp -d "${TMPDIR:-/tmp}/goodwalk-deploy.XXXXXX")"
+MAINTENANCE_ACTIVE=0
+
+clear_maintenance_flag() {
+  if (( MAINTENANCE_ACTIVE )) && (( nginx_args_present )); then
+    echo "[deploy-remote] Clearing maintenance flag"
+    "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" \
+      exec -T nginx rm -f /etc/nginx/conf.d/maintenance.flag || true
+    MAINTENANCE_ACTIVE=0
+  fi
+}
 
 cleanup() {
+  clear_maintenance_flag
   rm -rf "$STAGING_DIR"
 }
 
@@ -182,6 +193,70 @@ if [[ ! -f "$DEPLOY_PATH/.env" ]]; then
   fi
 fi
 
+merge_env_file() {
+  local template="$1"
+  local live="$2"
+
+  [[ -f "$template" ]] || { echo "[deploy-remote] No env template at $template, skipping merge"; return 0; }
+  [[ -f "$live" ]] || { echo "[deploy-remote] No live .env at $live, skipping merge"; return 0; }
+
+  local added diffs backup
+  added="$(mktemp)"
+  diffs="$(mktemp)"
+  backup="${live}.bak.$(date -u +%Y%m%dT%H%M%SZ)"
+
+  awk -v live="$live" -v added_log="$added" -v diff_log="$diffs" '
+    function trim(s) { sub(/^[ \t]+/,"",s); sub(/[ \t]+$/,"",s); return s }
+    BEGIN {
+      while ((getline line < live) > 0) {
+        if (line ~ /^[ \t]*#/ || line ~ /^[ \t]*$/) continue
+        eq = index(line, "=")
+        if (eq == 0) continue
+        k = trim(substr(line, 1, eq-1))
+        v = substr(line, eq+1)
+        live_keys[k] = v
+        live_seen[k] = 1
+      }
+      close(live)
+    }
+    /^[ \t]*#/ || /^[ \t]*$/ { next }
+    {
+      eq = index($0, "=")
+      if (eq == 0) next
+      k = trim(substr($0, 1, eq-1))
+      v = substr($0, eq+1)
+      if (!(k in live_seen)) {
+        print k "=" v >> added_log
+      } else if (live_keys[k] != v) {
+        print k "  (template=" v "  |  live=" live_keys[k] ")" >> diff_log
+      }
+    }
+  ' "$template"
+
+  if [[ -s "$added" ]]; then
+    cp "$live" "$backup"
+    echo "[deploy-remote] Adding env keys present in template but missing from $live:"
+    sed 's/^/    + /' "$added"
+    {
+      printf '\n# Appended by deploy-remote.sh on %s from deploy.env.template\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+      cat "$added"
+    } >> "$live"
+    echo "[deploy-remote] Backup of previous .env written to $backup"
+  else
+    echo "[deploy-remote] .env is up to date with template (no missing keys)"
+  fi
+
+  if [[ -s "$diffs" ]]; then
+    echo "[deploy-remote] NOTE: these keys exist in both files but values differ. Live values are PRESERVED:"
+    sed 's/^/    ! /' "$diffs"
+    echo "[deploy-remote] If a live value is stale (e.g. an old OWNER_EMAIL), edit $live and re-deploy."
+  fi
+
+  rm -f "$added" "$diffs"
+}
+
+merge_env_file "$DEPLOY_PATH/deploy.env.template" "$DEPLOY_PATH/.env"
+
 cd "$DEPLOY_PATH"
 
 echo "[deploy-remote] Validating compose configuration"
@@ -194,6 +269,39 @@ if [[ -n "$SERVICE_NAME" ]]; then
   fi
 fi
 
+if (( nginx_args_present )); then
+  [[ -f "$DEPLOY_PATH/$NGINX_SOURCE" ]] || fail "Nginx config missing from deployment payload: $DEPLOY_PATH/$NGINX_SOURCE"
+  [[ -f "$NGINX_COMPOSE_FILE" ]] || fail "Nginx compose file was not found on the server: $NGINX_COMPOSE_FILE"
+
+  MAINTENANCE_HTML_SRC="$DEPLOY_PATH/nginx/maintenance.html"
+  MAINTENANCE_LOGO_SRC="$DEPLOY_PATH/nginx/logo.png"
+  [[ -f "$MAINTENANCE_HTML_SRC" ]] || fail "Maintenance page missing from deployment payload: $MAINTENANCE_HTML_SRC"
+  [[ -f "$MAINTENANCE_LOGO_SRC" ]] || fail "Maintenance logo missing from deployment payload: $MAINTENANCE_LOGO_SRC"
+
+  echo "[deploy-remote] Updating shared nginx config (pre-rebuild) so maintenance routing is active"
+  mkdir -p "$(dirname "$NGINX_TARGET")"
+  cp "$DEPLOY_PATH/$NGINX_SOURCE" "$NGINX_TARGET"
+
+  echo "[deploy-remote] Installing maintenance page assets into nginx container"
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" \
+    exec -T nginx mkdir -p /var/www/html/m
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" \
+    cp "$MAINTENANCE_HTML_SRC" nginx:/var/www/html/maintenance.html
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" \
+    cp "$MAINTENANCE_LOGO_SRC" nginx:/var/www/html/m/logo.png
+
+  echo "[deploy-remote] Validating nginx configuration"
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" exec -T nginx nginx -t
+
+  echo "[deploy-remote] Reloading shared nginx so the new config (incl. maintenance routing) is live"
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" exec -T nginx nginx -s reload
+
+  echo "[deploy-remote] Engaging maintenance page (touch maintenance.flag)"
+  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" \
+    exec -T nginx touch /etc/nginx/conf.d/maintenance.flag
+  MAINTENANCE_ACTIVE=1
+fi
+
 if [[ -n "$SERVICE_NAME" ]]; then
   echo "[deploy-remote] Stopping only the Goodwalk service: $SERVICE_NAME"
   "${COMPOSE_CMD[@]}" -p "$PROJECT_NAME" -f "$COMPOSE_FILE" stop "$SERVICE_NAME" || true
@@ -216,19 +324,6 @@ if [[ -z "$SERVICE_NAME" || "$SERVICE_NAME" == "app" || "$SERVICE_NAME" == "db"
   "${COMPOSE_CMD[@]}" -p "$PROJECT_NAME" -f "$COMPOSE_FILE" exec -T app node scripts/sync-homepage-content.mjs
 fi
 
-if (( nginx_args_present )); then
+clear_maintenance_flag
-  [[ -f "$DEPLOY_PATH/$NGINX_SOURCE" ]] || fail "Nginx config missing from deployment payload: $DEPLOY_PATH/$NGINX_SOURCE"
-  [[ -f "$NGINX_COMPOSE_FILE" ]] || fail "Nginx compose file was not found on the server: $NGINX_COMPOSE_FILE"
-
-  echo "[deploy-remote] Updating shared nginx config to avoid stale container IPs"
-  mkdir -p "$(dirname "$NGINX_TARGET")"
-  cp "$DEPLOY_PATH/$NGINX_SOURCE" "$NGINX_TARGET"
-
-  echo "[deploy-remote] Validating nginx configuration"
-  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" exec -T nginx nginx -t
-
-  echo "[deploy-remote] Reloading shared nginx"
-  "${COMPOSE_CMD[@]}" -p "$NGINX_PROJECT_NAME" -f "$NGINX_COMPOSE_FILE" exec -T nginx nginx -s reload
-fi
 
 echo "[deploy-remote] Remote deployment finished"

src/lib/components/ServicesSection.svelte

@@ -25,7 +25,9 @@
           {/if}
 
           {#if service.href}
-            <a href={service.href} class="btn btn-green">Learn more</a>
+            <a href={service.href} class="btn btn-green">
+              Learn more<span class="visually-hidden"> about {service.title}</span>
+            </a>
           {/if}
         </div>
       {/each}

src/lib/styles/base.css

@@ -34,3 +34,15 @@ input,
 textarea {
   font: inherit;
 }
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}