docs: clarify Azure cold starts and deployment check

Author: venelouis

README.md

@@ -36,6 +36,14 @@ This monorepository contains three live cloud applications:
 
 All applications run in **Microsoft Azure Container Apps** on the **Azure for Students** plan using the Serverless Consumption Tier (Scale-to-Zero):
 
+> [!NOTE]
+> **Cold-start behavior:** these demos can scale to zero after being idle. The
+> first visit then has to wake a new Azure replica, so the page may load slowly
+> or briefly appear unavailable. Wait a few seconds and reload once. Persistent
+> failures should be checked in Azure revision and container logs. Keeping
+> `minReplicas = 1` avoids scale-to-zero wakeups at the cost of idle usage. See
+> the [Azure Container Apps deployment guide](docs/AZURE_CONTAINER_APPS.md#scale-to-zero-cold-start-notice).
+
 | Application | Live Public URL | Key Features | Admin / Cockpit |
 | :--- | :--- | :--- | :--- |
 | **🌐 Rullst Showcase** | [showcase.rullst.win](https://showcase.rullst.win) | 5 Web Paradigms, WAF Defense, LiveView, Active Record, Groq AI Copilot | 🛡️ **Nexus Admin:** [/nexus](https://rullst-showcase.redpond-24d9228d.eastus.azurecontainerapps.io/nexus)<br>🚀 **Studio:** [/studio](https://rullst-showcase.redpond-24d9228d.eastus.azurecontainerapps.io/studio)<br>*(Administrator credentials required)*<br>🤖 **Groq AI:** GPT-OSS 120B & Prompt Shield<br>📖 [Showcase Guide](docs/showcase-nexus-studio-ai-guide.md) |

docs/AZURE_CONTAINER_APPS.md

@@ -11,16 +11,16 @@ Why is Rullst the ultimate framework for serverless and cost-conscious cloud dep
 | Metric | 🦀 **Rullst (Rust)** | ☕ **Spring Boot (Java)** | 🐍 **Django / FastAPI (Python)** | 🐘 **Laravel (PHP)** |
 | :--- | :--- | :--- | :--- | :--- |
 | **Idle Memory (RAM)** | **~15–25 MB** | **~350–600 MB** (JVM overhead) | **~120–200 MB** (Gunicorn/Uvicorn) | **~150–250 MB** (PHP-FPM/Octane) |
-| **Cold-Start Wakeup** | **< 50 ms** (Instant) | **8–25 seconds** (JVM class loading) | **4–10 seconds** (Module imports) | **3–8 seconds** (Bootstrap & autoloader) |
-| **Scale-to-Zero Viability** | 🟢 **Perfect**: Users never notice a delay | 🔴 **Poor**: Frequent timeouts during wake-up | 🟡 **Moderate**: Noticeable cold lag | 🟡 **Moderate**: Noticeable cold lag |
+| **Application Process Startup** | **< 50 ms** in the measured binary | **8–25 seconds** (JVM class loading) | **4–10 seconds** (Module imports) | **3–8 seconds** (Bootstrap & autoloader) |
+| **Scale-to-Zero Viability** | 🟢 **Good for cost-sensitive demos**, with a user-visible platform cold start | 🔴 **Poor**: Frequent timeouts during wake-up | 🟡 **Moderate**: Noticeable cold lag | 🟡 **Moderate**: Noticeable cold lag |
 | **Minimum ACA Size Required** | **0.25 vCPU / 0.5 GiB** | **1.0 vCPU / 2.0 GiB** (Minimum viable) | **0.5 vCPU / 1.0 GiB** | **0.5 vCPU / 1.0 GiB** |
 | **Apps Fitting in Free Tier** | 🟢 **10–15 apps** fit comfortably | 🔴 **0–1 app** (exceeds free memory immediately) | 🟡 **1–2 apps** max | 🟡 **1–2 apps** max |
 | **Throughput (req/s per core)** | **~80,000+** (Zero-cost Tokio async) | **~15,000–25,000** | **~2,500–5,000** | **~3,000–6,000** |
 | **Estimated Monthly Cost** | **$0.00** (Full coverage under free grant) | **$25.00 – $45.00/mo** | **$12.00 – $20.00/mo** | **$12.00 – $20.00/mo** |
 
 ### 💡 Why Rullst Saves Over 90% in Cloud Infrastructure:
 1. **No Garbage Collection (GC) or JIT Runtime:** Rullst compiles directly to native machine code. There is no JVM or Python interpreter consuming hundreds of megabytes just to stay idle.
-2. **True Scale-to-Zero:** Because a Rullst container boots from zero in less than 50 milliseconds, you can aggressively configure replicas to drop to `0` when idle. When a visitor arrives, Azure wakes up the container in ~1 second, completely imperceptible to human browsing.
+2. **Scale-to-Zero with a Tradeoff:** The Rullst process starts quickly, but an Azure cold start also includes image availability, resource provisioning, container creation, initialization and health probes. The first request after an idle period can therefore be visibly slower and may briefly look unavailable. This is not guaranteed to be a one-second or imperceptible transition.
 3. **Massive Density:** On a single server or cloud plan, you can run 10x more Rullst microservices or tenant sites than equivalent Spring Boot or Django instances.
 
 ---
@@ -32,12 +32,37 @@ Why is Rullst the ultimate framework for serverless and cost-conscious cloud dep
 | **Idle Cost** | 💰 Charges **24/7**, even with 0 visitors (~$10–$15/mo). Depletes student credits in a few months. | 🟢 **$0.00** when idle (**Scale-to-Zero**). Replicas automatically shut down when traffic stops. | Rullst uses zero idle CPU/RAM when scaled to zero. |
 | **Monthly Free Grant** | ❌ Limited or expired free VM hours. | 🎁 **180,000 vCPU-seconds**, **360,000 GiB-seconds**, and **2,000,000 requests/month FREE**. | Your $100 credit lasts the **full 12 months** without depletion. |
 | **Regional Availability** | ⚠️ Frequent allocation failures in student accounts (*"QuotaExceeded"* / *"Regional capacity exhausted"* in `East US`, etc.). | ✅ Runs on Microsoft's elastic serverless fleet. No dedicated hardware reservation required. | Deploys reliably across regions without quota friction. |
-| **Cold-Start Latency** | N/A (always on). | ~1–2 seconds to wake up from zero. | Pure native Rust binary boots in **< 50ms**. Cold starts are imperceptible compared to Node.js/Python (10–30s). |
+| **Cold-Start Latency** | N/A (always on). | Variable and user-visible when waking from zero; it includes platform work beyond process startup. | The native Rust process starts quickly, but cannot eliminate Azure provisioning, image and probe latency. |
 | **OS Maintenance** | 🛠️ Manual: `apt upgrade`, SSH keys, Linux kernel patches, UFW firewall, systemd services. | 🛡️ Fully managed by Azure. Zero OS patching or infrastructure burden. | Focus purely on your Rust application and business logic. |
 | **TLS / HTTPS** | 🔐 Manual Let's Encrypt certbot setup and renewal cron jobs. | 🔒 **Automatic managed TLS/SSL certificate** with global Anycast routing. | Instant, zero-config HTTPS with custom domain support. |
 
 ---
 
+## Scale-to-Zero Cold-Start Notice
+
+These examples use **minimum replicas = 0** to preserve the Azure for Students
+budget. After an idle period, the next request starts a cold container. During
+that interval the browser may wait longer than usual or briefly show a gateway,
+connection or apparently broken-link error. Wait a few seconds and reload once.
+If the site remains unavailable, inspect the active revision, replica status,
+startup/readiness probes and container logs instead of assuming it is only cold.
+
+The Rullst binary's process startup time is only one component of the end-to-end
+cold start. Microsoft documents that scale-to-zero makes the next request trigger
+image/resource provisioning and application startup, and recommends client-side
+accommodations. See [Reducing cold-start time on Azure Container Apps](https://learn.microsoft.com/azure/container-apps/cold-start).
+
+For a user-facing service where first-request latency matters more than idle
+cost, configure **minimum replicas = 1**. This keeps an instance available but
+can incur idle charges. See [Scaling in Azure Container Apps](https://learn.microsoft.com/azure/container-apps/scale-app).
+
+This cold-start behavior is separate from revision rollout. In single-revision
+mode, Azure keeps the previous revision serving traffic until the new revision
+passes its startup and readiness checks; an app configured with zero minimum
+replicas can still cold-start later after becoming idle.
+
+---
+
 ## 🔒 Security Invariants & Production Defaults (Fail-Closed Architecture)
 
 When deploying Rullst applications to production, the framework enforces **Secure-by-Default (Fail-Closed)** invariants:
@@ -89,7 +114,7 @@ In the **Azure Portal**:
     - `PORT`: `3000`
     - `APP_ENV`: `production`
     - `NEXUS_ADMIN_USERNAME`: `rullst_admin`
-    - `NEXUS_ADMIN_PASSWORD`: `SovereignRullst2026!Key` (16+ characters)
+    - `NEXUS_ADMIN_PASSWORD`: reference a deployment secret containing 16+ characters; never commit or publish the value
 10. **Scale Rules (Scale-to-Zero):**
     - Set **Min replicas:** `0`
     - Set **Max replicas:** `1` (or scale dynamically with traffic)
@@ -113,13 +138,14 @@ az containerapp create \
   --max-replicas 1 \
   --cpu 0.25 \
   --memory 0.5Gi \
+  --secrets nexus-admin-password="$NEXUS_ADMIN_PASSWORD" \
   --env-vars \
     HOST=0.0.0.0 \
     PORT=3000 \
     RULLST_ENV=production \
     DATABASE_URL="sqlite:///app/db.sqlite?mode=rwc" \
     NEXUS_ADMIN_USERNAME=admin \
-    NEXUS_ADMIN_PASSWORD="SovereignPortfolio2026!"
+    NEXUS_ADMIN_PASSWORD=secretref:nexus-admin-password
 ```
 
 #### Via GitHub Actions (Automated CI/CD):
@@ -132,4 +158,4 @@ Upon committing and pushing to the `main` branch:
 
 ## 📊 Monitoring & Telemetry
 - **Live Logs:** In Azure Portal, navigate to **Application > Containers > Console log stream** to view real-time Rust logs.
-- **Zero Downtime Revisions:** Azure maintains traffic zero-downtime routing across revisions (`rullst-showcase--0000001`, `rullst-portfolio--0000001`).
+- **Revision Rollout:** In single-revision mode, Azure keeps the previous healthy revision serving until the new revision passes startup and readiness checks. This does not remove later scale-to-zero cold starts.

scripts/verify-deployment.py

@@ -88,7 +88,8 @@ def request(path, message=None, authenticated=False, cross_origin=False):
         data = None
         if message is not None:
             headers.update({"Origin": "https://invalid.example" if cross_origin else origin,
-                            "X-Rullst-AI": "1", "Sec-Fetch-Site": "same-origin",
+                            "X-Rullst-AI": "1",
+                            "Sec-Fetch-Site": "cross-site" if cross_origin else "same-origin",
                             "Content-Type": "application/x-www-form-urlencoded"})
             token = next((c.value for c in cookies if c.name == "rullst_csrf"), "")
             headers["X-CSRF-Token"] = token