Deploy FastAPI to GCP with Docker Compose

In this tutorial, you’ll deploy a FastAPI application to Google Cloud using the same Docker Compose workflow you use locally. Write a compose.yaml, test it with docker compose up, then deploy it to production GCP with one command.

Prerequisites

Before starting, make sure you have:

• Docker Desktop installed
• Defang CLI installed (brew install defang-io/defang/defang)
• A GCP project connected to Defang

Step 1: Create your FastAPI app

Create a simple FastAPI application with the following structure:

my-app/
├── app/
│   └── main.py
├── requirements.txt
├── Dockerfile
└── compose.yaml

Create app/main.py:

from fastapi import FastAPI
import os

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from GCP!"}

@app.get("/health")
def health_check():
    return {"status": "healthy"}

Step 2: Create a Dockerfile

Create a Dockerfile in your project root:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

# Cloud Run expects PORT environment variable
ENV PORT=8080
EXPOSE 8080

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

Create requirements.txt:

fastapi==0.109.0
uvicorn[standard]==0.27.0

Step 3: Create compose.yaml

Create a compose.yaml file. This is a standard Docker Compose file — nothing Defang-specific except the x-defang-postgres annotation for managed database provisioning:

services:
  web:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    x-defang-postgres: true

Test it locally first with docker compose up to make sure everything works. (For local dev, you can use a standard postgres:16 image instead of the x-defang-postgres annotation.)

Step 4: Deploy to GCP

The same Docker Compose file you just tested locally deploys directly to GCP:

defang compose up --provider=gcp

Defang will:

1. Build your FastAPI Docker image with Cloud Build
2. Push it to Artifact Registry
3. Create Cloud Run services
4. Provision a Cloud SQL PostgreSQL database
5. Configure networking and IAM

Step 5: Verify deployment

Check your running services:

defang services

You’ll see a table with your service endpoints. Open the endpoint URL in your browser to see your app.

Next steps

• Add a custom domain
• Set up CI/CD with GitHub Actions
• Add Redis caching with x-defang-redis: true
• Add MongoDB with x-defang-mongodb: true for Firestore
• Add managed LLMs with x-defang-llm: true for Vertex AI
• Create dev/staging/prod environments with defang stack new
• Deploy from your IDE with defang mcp setup --client=cursor