Deployment Checklist

Quick reference for deploying Prefect flows via CircleCI to your self-hosted Prefect server.

Pre-Deployment Checklist

Infrastructure

  • Platform infrastructure healthy (deployed from blog_infra)
  • Prefect server accessible at https://pipelines.rocketclub.online
  • ECR repository blog-data exists
  • ECS cluster rocket-club-prod-ecs running
  • VPC and networking configured

Prefect Server

  • Can access Prefect UI at https://pipelines.rocketclub.online
  • Have admin credentials (username:password)
  • Work pool blog-data-pool created
  • Work pool type is ECS
  • Work queue default exists

CircleCI Setup

  • GitHub repository connected to CircleCI
  • Project visible in CircleCI dashboard
  • All environment variables configured (see below)

Deployment Steps

1. Verify Configuration Files

  • .circleci/config.yml exists and is up to date
  • prefect.yaml exists with correct work pool name
  • Dockerfile exists and builds successfully
  • pyproject.toml has all dependencies

2. Test Locally (Optional)

# Build Docker image locally
docker build -t blog-data:test .

3. Push to Deployment Branch

# Commit your changes
git add .
git commit -m "feat: update flows"

# Push to deployment branch
git push origin main
# or
git push origin pipeline  # for testing

4. Monitor Deployment

CircleCI

  • Go to CircleCI dashboard
  • Find your workflow run
  • Monitor build-and-push-image job (~3-5 min)
  • Monitor deploy-to-prefect job (~2-3 min)
  • Verify both jobs complete successfully

ECR

# Verify image was pushed
aws ecr describe-images \
  --repository-name blog-data \
  --region eu-west-2 \
  --query 'imageDetails[0].[imageTags[0],imagePushedAt]' \
  --output table

Prefect Deployments

  • Go to https://pipelines.rocketclub.online
  • Navigate to Deployments
  • Verify data-pipeline-daily exists
  • Check version matches git commit hash
  • Verify schedule matches prefect.yaml (currently 0 2 */7 * * in America/New_York)

5. Test Flow Run

# Trigger a test run via CLI from within the VPC or a machine that can reach the internal Prefect API
export PREFECT_API_URL="https://pipelines.rocketclub.online/api"

prefect deployment run data-pipeline-daily

Or via Prefect UI:

  • Go to Deployments → data-pipeline-daily
  • Click "Run"
  • Monitor flow run in Flow Runs page
  • Verify flow completes successfully

Post-Deployment Verification

Flow Execution

  • Flow runs appear in Prefect UI
  • ECS tasks are created for flow runs
  • Logs are visible in Prefect UI
  • Flow completes successfully
  • Data is written to expected locations (S3, Neo4j)

Monitoring

  • Set up Prefect notifications for failures
  • Configure CloudWatch alarms for ECS tasks
  • Set up log aggregation (optional)

Troubleshooting

Build Fails

Check:

  • Dockerfile syntax is correct
  • All dependencies in pyproject.toml are valid
  • Base image is accessible

Fix:

# Test build locally
docker build -t blog-data:test .

Deployment Fails

Check:

  • PREFECT_API_URL is correct (ends with /api) if you are running Prefect CLI locally or from CI
  • Work pool blog-data-pool exists
  • Network connectivity to Prefect server from where you are running the CLI

Fix:

# Test Prefect connection (from inside the VPC or from a machine that can reach the Prefect API)
export PREFECT_API_URL="https://pipelines.rocketclub.online/api"
prefect work-pool ls

Flow Run Fails

Check:

  • ECS task has correct IAM permissions
  • Environment variables are set in ECS task
  • Docker image contains all required code
  • S3 buckets are accessible
  • Neo4j database is accessible

Fix:

# Check ECS task details
aws ecs describe-tasks \
  --cluster rocket-club-prod-ecs \
  --tasks <task-id> \
  --region eu-west-2

# Check Prefect worker logs
aws logs tail /ecs/prod/prefect-worker --follow --region eu-west-2

Quick Commands Reference

AWS

# List ECR images
aws ecr describe-images --repository-name blog-data --region eu-west-2
# List ECS tasks
aws ecs list-tasks --cluster rocket-club-prod-ecs --region eu-west-2

Prefect

# Configure Prefect CLI (optional; typically only used from within the VPC or an admin machine)
export PREFECT_API_URL="https://pipelines.rocketclub.online/api"

# List deployments
prefect deployment ls

# List work pools
prefect work-pool ls

# Trigger deployment
prefect deployment run data-pipeline-daily

# View flow runs
prefect flow-run ls --limit 10

CircleCI CLI

# Install CircleCI CLI (optional)
brew install circleci

# Validate config
circleci config validate

# View recent workflows
circleci workflow list <project-slug>

Rollback Procedure

If a deployment causes issues:

1. Identify Last Good Commit

# View recent commits
git log --oneline -10

# Find last working commit hash

2. Revert or Redeploy

Option A: Revert commit

git revert <bad-commit-hash>
git push origin main

Option B: Redeploy old version

# Update deployment to use old image
export OLD_IMAGE="<account-id>.dkr.ecr.eu-west-2.amazonaws.com/blog-data:<old-commit-hash>"

# Update deployment manually via Prefect UI or CLI

3. Verify Rollback

  • Check CircleCI build completes
  • Verify deployment in Prefect UI
  • Test flow run
  • Monitor for errors

Maintenance

Regular Tasks

  • Review flow run history weekly
  • Check ECS task resource usage
  • Monitor ECR storage usage
  • Update dependencies monthly
  • Review and rotate credentials quarterly

Updates

When updating flows:

  1. Make changes in feature branch
  2. Test locally
  3. Push to pipeline branch for testing
  4. Verify in Prefect UI
  5. Merge to main for production deployment

Support Resources

Summary

Yes Ready to Deploy when all items in "Pre-Deployment Checklist" are checked.

🚀 Deploy by pushing to main, pipeline, or ecs branch.

✓ Verify deployment in CircleCI, ECR, and Prefect UI.

🔍 Monitor flow runs and ECS tasks.

🔄 Rollback if needed using git revert or manual deployment update.

Up next

CircleCI Setup

Setting up CircleCI for pipeline CI/CD.