> ## Documentation Index
> Fetch the complete documentation index at: https://guardiandocs.korymsmith.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Deploy Guardian API to Google Cloud Run for production use

## Overview

Guardian API is deployed to **Google Cloud Run**, a fully managed serverless platform that automatically scales your containerized application. This guide covers deployment options and configuration.

## Quick Deploy

The fastest way to deploy Guardian API to production:

<Steps>
  <Step title="Prerequisites">
    * Google Cloud Platform account with billing enabled
    * `gcloud` CLI installed and configured
    * GitHub repository with backend code
  </Step>

  <Step title="Enable APIs">
    ```bash theme={null}
    gcloud services enable \
        cloudbuild.googleapis.com \
        run.googleapis.com \
        artifactregistry.googleapis.com
    ```
  </Step>

  <Step title="Create Artifact Registry">
    ```bash theme={null}
    gcloud artifacts repositories create guardian-api \
        --repository-format=docker \
        --location=us-central1 \
        --description="GuardianAPI Docker images"
    ```
  </Step>

  <Step title="Deploy with Cloud Build">
    ```bash theme={null}
    gcloud builds submit --config=backend/cloudbuild.yaml
    ```

    Your API will be deployed and accessible at a Cloud Run URL.
  </Step>
</Steps>

## Deployment Options

<Tabs>
  <Tab title="Cloud Build (Recommended)">
    **Automated CI/CD Pipeline**

    Cloud Build automatically builds and deploys your Docker container:

    ```bash theme={null}
    # Deploy with custom CORS origins
    gcloud builds submit --config=backend/cloudbuild.yaml \
        --substitutions=_CORS_ORIGINS="https://yourapp.com"
    ```

    **Benefits:**

    * Automatic builds from GitHub
    * Integrated with Cloud Run
    * Build caching for faster deployments
    * Configurable via `cloudbuild.yaml`

    **Build Configuration:**

    * Machine type: E2\_HIGHCPU\_8
    * Timeout: 20 minutes
    * Automatic tag: `latest` + commit SHA
  </Tab>

  <Tab title="Manual Deploy">
    **Build and Deploy Manually**

    For custom workflows or testing:

    ```bash theme={null}
    # Build Docker image
    cd backend
    docker build -t gcr.io/YOUR_PROJECT_ID/guardian-api:latest .

    # Push to Artifact Registry
    docker tag gcr.io/YOUR_PROJECT_ID/guardian-api:latest \
        us-central1-docker.pkg.dev/YOUR_PROJECT_ID/guardian-api/guardian-api:latest
    docker push us-central1-docker.pkg.dev/YOUR_PROJECT_ID/guardian-api/guardian-api:latest

    # Deploy to Cloud Run
    gcloud run deploy guardian-api \
        --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/guardian-api/guardian-api:latest \
        --region us-central1 \
        --platform managed \
        --allow-unauthenticated \
        --port 8080 \
        --memory 2Gi \
        --cpu 2 \
        --timeout 300 \
        --max-instances 10
    ```
  </Tab>

  <Tab title="Docker Compose (Local)">
    **Local Development**

    Run the full stack locally:

    ```bash theme={null}
    # Clone repository
    git clone https://github.com/Ksmith18skc/GuardianAPI.git
    cd GuardianAPI

    # Start services
    docker-compose up -d

    # API available at http://localhost:8000
    ```

    **Includes:**

    * FastAPI backend (port 8000)
    * Redis for rate limiting (port 6379)
    * Automatic model loading
  </Tab>
</Tabs>

## Cloud Run Configuration

### Resource Allocation

Production-ready configuration:

| Setting           | Value   | Purpose                                     |
| ----------------- | ------- | ------------------------------------------- |
| **Memory**        | 2Gi     | Sufficient for all ML models                |
| **CPU**           | 2 cores | Fast inference performance                  |
| **Timeout**       | 300s    | Allows model loading on cold start          |
| **Max Instances** | 10      | Scale to handle traffic spikes              |
| **Min Instances** | 0       | Scale to zero when idle (cost optimization) |

### Update Configuration

Change resource allocation after deployment:

```bash theme={null}
gcloud run services update guardian-api \
    --region us-central1 \
    --memory 4Gi \
    --cpu 2 \
    --timeout 300 \
    --max-instances 20
```

## Environment Variables

<AccordionGroup>
  <Accordion title="CORS_ORIGINS (Required)">
    **Purpose:** Specify which frontend domains can access your API

    **Format:** Comma-separated list of URLs

    **Example:**

    ```bash theme={null}
    CORS_ORIGINS=https://yourapp.com,https://staging.yourapp.com
    ```

    **Default:**

    * `https://guardian.korymsmith.dev`
    * `http://localhost:5173`
    * `http://127.0.0.1:5173`

    **Set in Cloud Run:**

    ```bash theme={null}
    gcloud run services update guardian-api \
        --set-env-vars CORS_ORIGINS=https://yourapp.com
    ```
  </Accordion>

  <Accordion title="LOG_LEVEL (Optional)">
    **Purpose:** Control logging verbosity

    **Options:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

    **Default:** `INFO`

    **Example:**

    ```bash theme={null}
    gcloud run services update guardian-api \
        --set-env-vars LOG_LEVEL=DEBUG
    ```
  </Accordion>

  <Accordion title="REDIS_URL (Optional)">
    **Purpose:** Enable rate limiting with Redis

    **Format:** `rediss://default:<token>@<host>:<port>`

    **Example (Upstash Redis):**

    ```bash theme={null}
    REDIS_URL=rediss://default:abc123@xyz.upstash.io:6379
    ```

    **Note:** Rate limiting fails open if not configured (allows all requests)

    **Set securely:**

    ```bash theme={null}
    # Store in Secret Manager
    gcloud secrets create redis-url --data-file=-
    # Paste your Redis URL and press Ctrl+D

    # Mount in Cloud Run
    gcloud run services update guardian-api \
        --update-secrets REDIS_URL=redis-url:latest
    ```
  </Accordion>

  <Accordion title="HUGGINGFACE_HUB_TOKEN (Optional)">
    **Purpose:** Improve HuggingFace model download reliability

    **Note:** Public models don't require a token, but having one can help with rate limits

    **Get token:** [HuggingFace Settings](https://huggingface.co/settings/tokens)

    **Set securely:**

    ```bash theme={null}
    gcloud run services update guardian-api \
        --update-secrets HUGGINGFACE_HUB_TOKEN=hf-token:latest
    ```
  </Accordion>
</AccordionGroup>

## Continuous Deployment

Set up automatic deployments when you push to GitHub:

<Steps>
  <Step title="Connect Repository">
    ```bash theme={null}
    gcloud builds triggers create github \
        --repo-name=GuardianAPI \
        --repo-owner=YOUR_GITHUB_USERNAME \
        --branch-pattern="^main$" \
        --build-config=backend/cloudbuild.yaml
    ```
  </Step>

  <Step title="Configure Trigger Settings">
    In the Google Cloud Console:

    * Navigate to Cloud Build > Triggers
    * Find your trigger
    * Add substitution variables:
      * `_CORS_ORIGINS`: Your frontend URL
      * `_LOG_LEVEL`: `INFO` (or `DEBUG`)
  </Step>

  <Step title="Automatic Deployments">
    Every push to `main` now:

    1. Triggers Cloud Build
    2. Builds Docker image
    3. Pushes to Artifact Registry
    4. Deploys to Cloud Run
    5. Creates new revision
  </Step>
</Steps>

## Health Monitoring

### Health Endpoint

Check API health and model status:

```bash theme={null}
# Get your Cloud Run URL
SERVICE_URL=$(gcloud run services describe guardian-api \
    --region us-central1 \
    --format 'value(status.url)')

# Check health
curl ${SERVICE_URL}/v1/health
```

**Expected Response:**

```json theme={null}
{
  "status": "healthy",
  "models": {
    "sexism": "loaded",
    "toxicity": "loaded",
    "rules": "loaded"
  }
}
```

### View Logs

Monitor your API in real-time:

```bash theme={null}
# Real-time logs
gcloud run services logs tail guardian-api --region us-central1

# Historical logs (last 50 entries)
gcloud run services logs read guardian-api --region us-central1 --limit 50
```

### Cloud Run Metrics

View in Google Cloud Console:

* Request count and rate
* Response latency (p50, p95, p99)
* Error rate
* Instance count
* Memory and CPU usage

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service Won't Start">
    **Check logs:**

    ```bash theme={null}
    gcloud run services logs read guardian-api --region us-central1
    ```

    **Common issues:**

    * Missing dependencies in `requirements.txt`
    * Python version mismatch (requires 3.11+)
    * Model files not included in Docker build
    * Insufficient memory allocation (needs 2Gi minimum)
  </Accordion>

  <Accordion title="Models Not Loading">
    **Symptoms:**

    * Health endpoint shows models as "not loaded"
    * Moderation requests fail with 500 errors

    **Solutions:**

    1. Check logs for HuggingFace download errors
    2. Verify sufficient memory (2Gi recommended)
    3. Add `HUGGINGFACE_HUB_TOKEN` if rate limited
    4. Increase timeout to 300s for model loading
  </Accordion>

  <Accordion title="CORS Errors">
    **Symptoms:**

    * Frontend can't connect to API
    * Browser console shows CORS errors

    **Solutions:**

    1. Verify `CORS_ORIGINS` includes your frontend URL
    2. Check for exact match (including `https://`)
    3. Avoid trailing slashes in URLs
    4. Verify environment variable is set:
       ```bash theme={null}
       gcloud run services describe guardian-api \
           --format 'value(spec.template.spec.containers[0].env)'
       ```
  </Accordion>

  <Accordion title="Cold Start Delays">
    **Cause:** Cloud Run scales to zero when idle

    **Behavior:** First request after idle takes 10-30 seconds

    **Solutions:**

    * **Accept delay** (most cost-effective)
    * **Set minimum instances:**
      ```bash theme={null}
      gcloud run services update guardian-api \
          --min-instances 1
      ```
      Note: This prevents scale-to-zero (increases cost)
    * **Use Cloud Scheduler** to ping API every 5 minutes
  </Accordion>
</AccordionGroup>

## Cost Optimization

### Free Tier

Google Cloud Run includes generous free tier:

* **2 million requests/month**
* **360,000 GB-seconds of memory**
* **180,000 vCPU-seconds**

Most small to medium applications stay within free tier.

### Cost Management

<CardGroup cols={2}>
  <Card title="Scale to Zero" icon="arrow-down">
    Set `min-instances=0` to avoid charges when idle

    **Savings:** Only pay for actual usage

    **Trade-off:** Cold start delays
  </Card>

  <Card title="Right-Size Resources" icon="gauge">
    Start with 2Gi memory and scale if needed

    **Monitor:** Check Cloud Run metrics for actual usage

    **Adjust:** Increase only if hitting limits
  </Card>

  <Card title="Set Billing Alerts" icon="bell">
    Configure budget alerts in GCP

    **Recommended:** Alert at 50%, 80%, 100% of budget

    **Prevents:** Unexpected charges
  </Card>

  <Card title="Limit Max Instances" icon="stop">
    Cap auto-scaling to prevent runaway costs

    **Recommended:** Start with 10 max instances

    **Adjust:** Based on traffic patterns
  </Card>
</CardGroup>

## Security Best Practices

<Steps>
  <Step title="Use Secret Manager">
    Never commit secrets to repository:

    ```bash theme={null}
    # Store Redis URL securely
    echo "rediss://your-redis-url" | gcloud secrets create redis-url --data-file=-

    # Mount in Cloud Run
    gcloud run services update guardian-api \
        --update-secrets REDIS_URL=redis-url:latest
    ```
  </Step>

  <Step title="Configure CORS Properly">
    Only allow specific frontend origins:

    ```bash theme={null}
    # Good: Specific domains
    CORS_ORIGINS=https://yourapp.com,https://staging.yourapp.com

    # Bad: Wildcard (never use in production)
    CORS_ORIGINS=*
    ```
  </Step>

  <Step title="Enable Rate Limiting">
    Configure Redis to prevent abuse:

    ```bash theme={null}
    # Set up Upstash Redis
    # Get URL from https://upstash.com

    # Configure in Cloud Run
    gcloud run services update guardian-api \
        --update-secrets REDIS_URL=redis-url:latest
    ```

    See [Rate Limiting](/configuration/rate-limiting) for details.
  </Step>

  <Step title="Monitor Logs">
    Regularly check logs for suspicious activity:

    ```bash theme={null}
    # Check for errors
    gcloud run services logs read guardian-api \
        --region us-central1 \
        --filter="severity>=ERROR"
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Environment" icon="gear" href="/configuration/environment">
    Set up environment variables and configuration
  </Card>

  <Card title="Enable Rate Limiting" icon="shield" href="/configuration/rate-limiting">
    Protect your API with rate limiting
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/moderate-text">
    Explore API endpoints and schemas
  </Card>

  <Card title="Architecture Guide" icon="sitemap" href="/concepts/architecture">
    Understand the system architecture
  </Card>
</CardGroup>

## Additional Resources

* **Detailed Deployment Guide:** `backend/DEPLOYMENT.md` in repository
* **Cloud Build Config:** `backend/cloudbuild.yaml`
* **Google Cloud Run Docs:** [cloud.google.com/run](https://cloud.google.com/run/docs)
* **Docker Configuration:** `backend/Dockerfile`

## Production Checklist

Before going live, verify:

<Checklist>
  * [ ] Backend deployed to Cloud Run
  * [ ] Health endpoint returns healthy status
  * [ ] All models loaded successfully
  * [ ] CORS configured with production frontend URL
  * [ ] Environment variables set correctly
  * [ ] Redis configured for rate limiting (optional)
  * [ ] Billing alerts configured
  * [ ] Cloud Run metrics monitored
  * [ ] Frontend updated with Cloud Run API URL
  * [ ] End-to-end testing completed
</Checklist>