Skip to content

Macumba Backend Deployment Guide

This document outlines how to deploy the Macumba FastAPI backend to different environments and cloud providers.

Deployment Options

The application can be deployed to:

  1. Cloud Providers:
  2. AWS ECS Fargate

  3. Google Cloud Run

  4. Environments:

  5. dev (Development)
  6. stg (Staging)
  7. prod (Production)

GitHub Actions Deployment

The simplest way to deploy is using our unified deployment workflow that lets you select both the environment and cloud provider:

  1. Navigate to the GitHub repository's "Actions" tab
  2. Select "Deploy Macumba Backend" from the workflows list
  3. Click "Run workflow"
  4. Select:
  5. Environment: dev, stg, or prod
  6. Cloud Provider: aws or gcp
  7. Run database setup scripts?: Check this box if you need to run setup_db.py and populate_airports.py (e.g., for a new environment or major schema change). Defaults to false (unchecked). This applies to both AWS and GCP deployments.
  8. Click "Run workflow" to start the deployment

Unified Deployment Workflow

Option 2: Provider-Specific Workflows

You can also use the provider-specific workflows directly:

AWS Deployment

  1. Navigate to the GitHub repository's "Actions" tab
  2. Select "Deploy FastAPI Backend to AWS" from the workflows list
  3. Click "Run workflow"
  4. Select the environment (dev, stg, or prod)
  5. Run database setup scripts?: Check this box if you need to run setup_db.py and populate_airports.py. Defaults to false.
  6. Click "Run workflow"

GCP Deployment

  1. Navigate to the GitHub repository's "Actions" tab
  2. Select "Deploy FastAPI Backend" (this is the deploy-fastapi.yml for Cloud Run) from the workflows list
  3. Click "Run workflow"
  4. Select the environment (dev, stg, or prod)
  5. Run database setup scripts?: Check this box if you need to run setup_db.py and populate_airports.py. Defaults to false.
  6. Click "Run workflow"

Environment Configuration

Each environment has its own configuration setup:

AWS Environments

  • Development:
  • Cluster: macumba-dev-cluster
  • Service: macumba-dev-fastapi

  • Resources: 256 CPU units, 512MB memory

  • Staging:

  • Cluster: macumba-stg-cluster
  • Service: macumba-stg-fastapi

  • Resources: 256 CPU units, 512MB memory

  • Production:

  • Cluster: macumba-prod-cluster
  • Service: macumba-prod-fastapi
  • Resources: 512 CPU units, 1024MB memory

GCP Environments

  • Development:
  • Service: macumba-travel-backend-dev
  • Region: australia-southeast1

  • Resources: 1 CPU, 2GB memory

  • Staging:

  • Service: macumba-travel-backend-stg
  • Region: australia-southeast1

  • Resources: 1 CPU, 2GB memory

  • Production:

  • Service: macumba-travel-backend-prod
  • Region: australia-southeast1
  • Resources: 1 CPU, 2GB memory

Database Setup Scripts Execution

When the "Run database setup scripts?" option is checked for either AWS or GCP deployments:

  • AWS: One-off ECS tasks are launched to execute scripts/setup_db.py and scripts/populate_airports.py against the RDS database.
  • GCP: The GitHub Actions workflow runner will:
    1. Download and start the Cloud SQL Proxy to connect to the specified Cloud SQL instance.
    2. Execute scripts/setup_db.py and scripts/populate_airports.py using this proxied connection.
    3. Stop the Cloud SQL Proxy.

This ensures that database initialization and data population are handled consistently and can be optionally triggered for both cloud providers.

Troubleshooting

Common AWS Deployment Issues

  1. Permission Errors:
  2. Verify the GitHub Actions role has the necessary permissions in the AWS account

  3. Check IAM configuration in infra/terraform_aws/github_actions_oidc.tf

  4. Database Initialization Fails:

  5. Check the CloudWatch logs for the ECS task
  6. Ensure database connectivity from the ECS task

Common GCP Deployment Issues

  1. Permission Errors:
  2. Verify the GitHub Actions service account has necessary permissions

  3. Check IAM configuration in Google Cloud Console

  4. Secret Access Issues:

  5. Ensure all required secrets exist in Google Secret Manager
  6. Verify the service account has access to read these secrets

Manual Deployment

AWS Manual Deployment

For manual AWS deployment, refer to detailed instructions in AWS_DEPLOYMENT.md.

GCP Manual Deployment

For manual GCP deployment, refer to detailed instructions in GCP_DEPLOYMENT.md.