azure-container-apps-deployment

Files (9)

• SKILL.md
• container-app-command-format.md · references/
• custom-domain-setup.md · references/
• dockerfile-cpu-only.md · references/
• docling-import-fix.md · references/
• github-pages-frontend-update.md · references/
• healthz-endpoint.md · references/
• region-policy-workaround.md · references/
• gh-pages-index.html · templates/

SKILL.md (first lines)

# Azure Container Apps Deployment Skill

Deploy containerized Python apps (FastAPI, RAG, agent backends) to Azure Container Apps with cost optimization for free/student subscriptions.

## When to Use

- Deploying a containerized Python backend (FastAPI, RAG API, agent server) to Azure
- Target is Azure Container Apps (serverless containers, scale-to-zero)
- Subscription has region/policy restrictions (e.g., Azure for Students)
- Need cost optimization: scale-to-zero, no persistent Log Analytics, minimal resources

## Prerequisites

- Azure subscription with Contributor access on a resource group
- Docker image pushed to a public registry (GHCR, Docker Hub) or private ACR
- Azure CLI installed and authenticated (`az login`)
- Resource group created

## Procedure

### 1. Prepare the Docker Image

```dockerfile
# Multi-stage build for minimal size
FROM python:3.11-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ libpq-dev && rm -rf /var/lib/apt/lists/*
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip setuptools wheel \
    && pip install --no-cache-dir --extra-index-url https://download.pytorch.org/whl/cpu -r requirements.txt

FROM python:3.11-slim AS runtime
RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libgomp1 libpq5 ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser -s /bin/bash appuser
WORKDIR /app
COPY --chown=appuser:appuser . .
RUN mkdir -p /app/rag_vector_db /app/rag_pdfs /app/dashboard_log && chown -R appuser:appuser /app
USER appuser
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 HOST=0.0.0.0 PORT=8000 TOKENIZERS_PARALLELISM=false OMP_NUM_THREADS=1 MKL_NUM_THREADS=1
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz', timeout=5)" || exit 1
EXPOSE 8000
CMD ["gunicorn", "server:app", "--workers", "1", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000", "--timeout", "120", "--keep-alive", "5", "--max-requests", "1000", "--max-requests-jitter", "50", "--preload"]
```

Key optimizations:
- Use `--extra-index-url https://download.pytorch.org/whl/cpu` for CPU-only PyTorch (avoids CUDA bloat)
- Pin docling version (`docling==1.20.0`) to avoid dependency resolution hell
- Use `gunicorn` with `--preload` for memory sharing
- Single worker, uvicorn worker class
- Health check endpoint `/healthz` (no DB calls)

### 2. Build & Push Image

```bash
docker build -t ghcr.io/<owner>/<repo>:latest .
docker push ghcr.io/<owner>/<repo>:latest
```

Or use GitHub Actions (`.github/workflows/build-push.yml`) for automated builds.

### 3. Create Container Apps Environment (CLI)

**Critical for restricted subscriptions (Azure for Students):**

```bash
# Try Central US first (most commonly allowed)
az containerapp env create --name <env-name> --resource-group <rg> --location "Central US" --logs-destination none

# If Log Analytics required, create workspace in allowed region first:
az monitor log-analytics workspace create --resource-group <rg> --workspace-name <ws-name> --location "Central US"
$workspaceId = az monitor log-analytics workspace show -g <rg> -n <ws-name> --query customerId -o tsv
$workspaceKey = az monitor log-analytics workspace get-shared-keys -g <rg> -n <ws-name> --query primarySharedKey -o tsv
az containerapp env create --name <env-name> --resource-group <rg> --location "Central US" --logs-workspace-id $workspaceId --logs-workspace-key $workspaceKey
```

**Key flags:**
- `--logs-destination none` — skip Log Analytics entirely (saves cost, avoids region restrictions)
- `--logs-workspace-id/key` — use pre-created workspace in allowed region

### 4. Create Container App (CLI)

```bash
az containerapp create \
  --name <app-name> \
  --resource-group <rg> \
  --environment <env-name> \
  --image ghcr.io/<owner>/<repo>:latest \
  --target-port 8000 \
  --ingress external \
  --min-replicas 0 \
  --max-replicas 3 \
  --cpu 1.0 \
  --memory 2Gi \
  --secrets openrouter-api-key="<key>" \
  --env-vars \
    OPENROUTER_API_KEY=secretref:openrouter-api-key \
    RAG_PDF_SOURCE=github \
    RAG_GITHUB_REPO=<owner>/<repo> \
    RAG_GITHUB_PATH=pdfs \
    RAG_GITHUB_REF=main \
    CHROMA_DB_DIR=/data/rag_vector_db \
    HOST=0.0.0.0 \
    PORT=8000
```

**Cost optimization settings:**
- `--min-replicas 0` — scale to zero when idle (no charge)
- `--max-replicas 3` — limit max cost
- `--cpu 1.0 --memory 2Gi` — minimal viable for docling + ChromaDB
- Single container, no sidecars

### 5. Portal Alternative

If CLI fails due to policy, use Azure Portal:
1. **Container Apps Environments** → Create → Region: Central US → Log Analytics: None
2. **Container Apps** → Create → Select environment → Image: `ghcr.io/...` → Ingress: HTTP, port 8000 → CPU: 1, Memory: 2Gi → Min replicas: 0, Max: 3

From RekapalliVasudeva-MBU/aether-desktop, MIT.

More from RekapalliVasudeva-MBU/aether-desktop