Deploy to Staging

This guide covers the workflow for deploying code changes to the staging environment on AWS ECS Fargate.

Deployment Workflow

The staging deployment is automated through GitHub Actions. Here's the flow:

feature branch → develop branch → CI pipeline → ECR → ECS Fargate

Step 1: Create a Feature Branch

Start by creating a feature branch from develop:

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Follow the Git Workflow Guide for branch naming conventions.

Step 2: Make Your Changes

Develop your feature locally. Test thoroughly:

# Run tests
pytest

# Run the linter
flake8 app/

# Format code
black app/

# Type check (if using mypy)
mypy app/

Step 3: Commit and Push

Commit your changes with meaningful messages:

git add .
git commit -m "feat: add user profile endpoint"
git push origin feature/your-feature-name

Step 4: Create a Pull Request

Create a PR on GitHub from your feature branch to develop:

• Go to the menotime-api repository
• Click "New Pull Request"
• Set base branch to develop, compare to your feature branch
• Fill in the PR title and description
• Add reviewers

PR Checklist

Ensure your PR includes:

• ✅ A clear description of the changes
• ✅ Reference to related issues (e.g., "Closes #123")
• ✅ All tests passing
• ✅ Updated documentation if needed
• ✅ Database migration file (if schema changes)
• ✅ Environment variables added to .env.example (if needed)

Step 5: Code Review

Wait for at least one code review approval. Address any comments:

# Make requested changes
git add .
git commit -m "refactor: improve error handling based on review"
git push origin feature/your-feature-name

Step 6: Merge to Develop

Once approved, merge your PR:

# Option 1: Merge via GitHub UI (recommended)
# Click "Squash and merge" or "Create a merge commit"

# Option 2: Command line
git checkout develop
git pull origin develop
git merge feature/your-feature-name
git push origin develop

Step 7: Automated CI/CD Pipeline Runs

When you push to develop, GitHub Actions automatically:

1. Runs Tests — Ensures all tests pass
2. Builds Docker Image — Creates a new container image
3. Pushes to ECR — Uploads the image to AWS Elastic Container Registry
4. Updates ECS Service — Deploys the new image to staging ECS cluster
5. Health Check — Verifies the service is healthy

You can monitor progress in GitHub:

Actions tab → Select your workflow run → View logs

Understanding the CI/CD Pipeline

The .github/workflows/deploy-staging.yml file defines the pipeline:

name: Deploy to Staging
on:
  push:
    branches:
      - develop
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: pytest
  build-and-push:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Build Docker image
        run: docker build -t menotime:${{ github.sha }} .
      - name: Push to ECR
        run: aws ecr get-login-password | docker login --username AWS --password-stdin $ECR_REGISTRY
      - name: Deploy to ECS
        run: aws ecs update-service --cluster staging --service menotime-api --force-new-deployment

Verifying the Staging Deployment

After the pipeline completes, verify that staging is working:

Check ECS Task Status

aws ecs list-tasks \
  --cluster staging \
  --service-name menotime-api \
  --region us-west-1

Get task details:

aws ecs describe-tasks \
  --cluster staging \
  --tasks arn:aws:ecs:us-west-1:ACCOUNT_ID:task/staging/TASK_ID \
  --region us-west-1

Expected output includes lastStatus: RUNNING.

Check API Health

curl https://staging.menotime-api.timelessbiotech.com/health
# {"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}

Check Logs

View logs in CloudWatch:

aws logs tail /ecs/menotime-api-staging --follow --region us-west-1

Or in the AWS Console:

1. Go to CloudWatch → Log Groups
2. Select /ecs/menotime-api-staging
3. View recent log streams

Test Key Endpoints

Test critical endpoints in staging:

# Health check
curl https://staging.menotime-api.timelessbiotech.com/health

# List patients (requires auth token)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://staging.menotime-api.timelessbiotech.com/api/v1/patients

# Create a test patient
curl -X POST https://staging.menotime-api.timelessbiotech.com/api/v1/patients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "email": "test@example.com",
    "first_name": "Test",
    "last_name": "User"
  }'

Rollback Procedure

If there's a critical issue in staging, roll back to the previous version:

Option 1: Revert the Commit

If the issue is in the most recent commit:

git checkout develop
git revert HEAD  # Creates a new commit that reverses changes
git push origin develop

This triggers another CI/CD pipeline run with the reverted code.

Option 2: Manually Restart Previous ECS Task

If you need to immediately rollback:

# List task definitions for menotime-api
aws ecs list-task-definitions \
  --family-prefix menotime-api-staging \
  --region us-west-1

# Update the service to use a previous task definition
aws ecs update-service \
  --cluster staging \
  --service menotime-api \
  --task-definition menotime-api-staging:PREVIOUS_REVISION \
  --region us-west-1

Option 3: Revert in GitHub

If the commit hasn't been tested yet:

git revert COMMIT_SHA
git push origin develop

Monitoring After Deployment

After deploying to staging, monitor for issues:

CloudWatch Alarms

Check if any alarms are triggered:

aws cloudwatch describe-alarms \
  --region us-west-1 \
  --query 'MetricAlarms[?StateValue==`ALARM`]'

Error Rate

Monitor error logs:

aws logs filter-log-events \
  --log-group-name /ecs/menotime-api-staging \
  --filter-pattern "ERROR" \
  --region us-west-1

Database Connections

Check database connection pool:

aws rds describe-db-instances \
  --db-instance-identifier menotime-staging \
  --region us-west-1

Staging Environment Details

Property	Value
ECS Cluster	staging
ECS Service	menotime-api
Task Definition	menotime-api-staging
Container Port	8000
Load Balancer	Application Load Balancer (ALB)
Database	RDS PostgreSQL (menotime-staging)
Base URL	https://staging.menotime-api.timelessbiotech.com
Region	us-west-1

Troubleshooting

Deployment stuck in "In Progress"

# Check task status
aws ecs describe-services \
  --cluster staging \
  --services menotime-api \
  --region us-west-1

# Force a new deployment
aws ecs update-service \
  --cluster staging \
  --service menotime-api \
  --force-new-deployment \
  --region us-west-1

Task failing to start

# Check task logs
aws logs tail /ecs/menotime-api-staging --follow --region us-west-1

# Inspect task details
aws ecs describe-tasks \
  --cluster staging \
  --tasks arn:aws:ecs:us-west-1:ACCOUNT_ID:task/staging/TASK_ID \
  --region us-west-1 | jq '.tasks[0].containers[0].lastStatus'

Database migration failed

# Exec into a running task
aws ecs execute-command \
  --cluster staging \
  --task TASK_ID \
  --container menotime-api \
  --interactive \
  --command "/bin/bash" \
  --region us-west-1

# Inside the container, check migration status
alembic current
alembic history --oneline

Related Guides

• Local Development Setup
• Database Migrations
• Git Workflow
• Deploy to Production