docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566

Problem

Azure Container Apps is the natural lowest-friction production hosting target for Squad (managed KEDA, managed TLS, scaling to zero), and AKS is required for teams that need full Kubernetes control. Neither is documented. keda-scaling.md documents KEDA ScaledObjects but assumes the container image and Deployment already exist. dual-mode-deployment.md documents env vars but has no Dockerfile. Users hit a complete dead end at "how do I actually run this in the cloud."

Parent issue: #1564

Scope

Three new pages:

Page A — Dockerfile reference: docs/src/content/docs/reference/container-image.md

• Minimal Dockerfile for @bradygaster/squad-cli; multi-stage build; non-root user
• Env-var contract table (SQUAD_DEPLOYMENT_MODE, SQUAD_POD_ID, OTEL_EXPORTER_OTLP_ENDPOINT, GITHUB_COPILOT_CLI_PATH) with required/optional status
• Mounting .squad/ via volume vs baking in; tradeoffs
• Secret injection: env var (insecure), mounted secret, Azure Key Vault CSI driver
• GHCR and ACR push commands
• Note open bug FSStorageProvider constructed without rootDir in resolveSquadState() — state writes land in repo root instead of .squad/ #1555 (FSStorageProvider rootDir): volume-mounted state backend requires explicit rootDir config as a workaround until fixed

Page B — Azure Container Apps scenario: docs/src/content/docs/scenarios/azure-container-apps.md

• Reader goes from zero to a running Squad agent in ACA
• az containerapp create, env-var injection, managed identity for GitHub API calls
• KEDA HTTP/queue scaler + built-in HTTP scaling comparison
• ACA Jobs for one-shot issue dispatch
• Scaling to zero — cold start tradeoffs
• Troubleshooting: missing env vars, KEDA not triggering, cold-start failures
• Cross-link: keda-scaling.md, dual-mode-deployment.md, features/external-state.md

Page C — AKS deployment runbook: docs/src/content/docs/scenarios/aks-deployment.md

• Prerequisites: AKS cluster, KEDA, ACR, Workload Identity
• Image build + push, Deployment YAML, KEDA ScaledObject wiring
• Azure Workload Identity (pod-managed identity) for token-free auth — replaces long-lived PATs
• ConfigMap for .squad/ state; Persistent Volume for state backend
• kubectl troubleshooting: OOMKilled, KEDA not firing, GitHub API 401, state backend contention
• Upgrade strategy
• Cross-link: keda-scaling.md, dual-mode-deployment.md, Page A above

Acceptance Criteria

• Page A: Dockerfile compiles and runs squad watch --execute inside a container
• Page A: All env vars with required/optional status in a table; secret injection patterns (env, mounted, Key Vault CSI) covered
• Page A: FSStorageProvider constructed without rootDir in resolveSquadState() — state writes land in repo root instead of .squad/ #1555 (FSStorageProvider rootDir) documented with workaround
• Page B: Reader with an Azure subscription can deploy a working Squad agent in ACA end-to-end
• Page B: Managed identity section replaces PAT-based auth
• Page C: Reader with an existing AKS cluster + ACR can deploy Squad
• Page C: Workload Identity replaces long-lived PATs
• Page C: Troubleshooting section covers ≥4 concrete failure modes with kubectl commands
• State backend warning: explicit note that branch-based (orphan) state is NOT safe for concurrent writes from multiple pods; link to features/state-backends.md and [External State] Tracking: command and docs integration gaps #1402

Non-Goals

• Replacing the Azure Container Apps or AKS official docs
• Covering ACA Dynamic Sessions or Sandboxes (tracked in companion issue docs milestone: real-world Squad hosting, integrations, and operations #1564/CHILD-5)
• Helm chart authoring

Source / Inspiration

Tamir Dresher published posts describing Squad hosting on AKS with Helm/KEDA/Workload Identity, and a reference repo. These are inspiration and citation sources — content must be written in Squad voice, not copied.

Relation to Existing Issues

• [Cross-Squad] Design input: squad watch --execute --remote (ADC dispatch) #1189 — Adjacent (not duplicate). [Cross-Squad] Design input: squad watch --execute --remote (ADC dispatch) #1189 is an architecture RFC for --remote dispatch; this issue is the current deployment guide. Cross-linked.
• [External State] Tracking: command and docs integration gaps #1402 — Page C state backend warning cross-links to this issue for external state gaps.
• FSStorageProvider constructed without rootDir in resolveSquadState() — state writes land in repo root instead of .squad/ #1555 — Page A documents the open FSStorageProvider bug and workaround.
• docs milestone: real-world Squad hosting, integrations, and operations #1564 — Parent umbrella.

Priority

P0 — Zero ACA coverage; highest-value production gap after MAF integration. Page A should ship before or with Pages B and C since both reference it.