Deploy

Deploy

Build, push, and deploy SerpentStack to AWS using Docker and Terraform.

Environments

• dev -- automatic deploys from main, auto-approve on apply
• staging -- manual trigger, shows plan for review before apply
• prod -- manual trigger, requires plan review before apply

All Terraform config lives in infra/environments/{env}/.

Quick Deploy

make deploy              # Deploy to dev (default)
make deploy env=staging  # Deploy to staging
make deploy env=prod     # Deploy to production

Or use the GitHub Actions CD pipeline — it runs automatically on push to main when AWS credentials are configured as repository secrets.

Step-by-Step Manual Deploy

Step 1: Build Docker Images

docker build -t serpentstack-backend:latest ./backend
docker build -t serpentstack-frontend:latest ./frontend

Tag with the git SHA for traceability:

GIT_SHA=$(git rev-parse --short HEAD)
docker tag serpentstack-backend:latest serpentstack-backend:$GIT_SHA
docker tag serpentstack-frontend:latest serpentstack-frontend:$GIT_SHA

Step 2: Push to ECR

Authenticate with ECR (replace ACCOUNT_ID and REGION):

aws ecr get-login-password --region $AWS_REGION | \
  docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

Tag and push both images:

docker tag serpentstack-backend:$GIT_SHA $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/serpentstack-backend:$GIT_SHA
docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/serpentstack-backend:$GIT_SHA

docker tag serpentstack-frontend:$GIT_SHA $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/serpentstack-frontend:$GIT_SHA
docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/serpentstack-frontend:$GIT_SHA

Step 3: Terraform Plan

cd infra/environments/{env}
terraform init
terraform plan -var="app_image_tag=$GIT_SHA" -out=tfplan

Review the plan output carefully. Look for:

• Resources being destroyed: unexpected destroys indicate a config drift. Investigate before proceeding.
• Security group changes: verify no ports are being opened unintentionally.
• Database modifications: any RDS changes should be treated as high-risk.

Step 4: Terraform Apply

Only after the plan is reviewed and approved:

cd infra/environments/{env}
terraform apply tfplan

For dev, the deploy script auto-approves. For staging and prod, always require explicit confirmation.

Step 5: Post-Deploy Health Check

Wait 30 seconds for App Runner to provision the new revision, then verify:

APP_URL=$(cd infra/environments/{env} && terraform output -raw app_url)
curl -sf $APP_URL/api/v1/health | jq .

Expected response:

{"status": "healthy", "version": ""}

If the health check fails:

1. Check App Runner service logs in the AWS console or via CLI: aws apprunner list-operations --service-arn .
2. Check if the new revision deployed: aws apprunner describe-service --service-arn | jq '.Service.Status'.
3. Check CloudWatch logs for the App Runner service.

Step 6: Rollback

If the deploy is broken, revert to the previous image tag:

# Find the previous working tag
PREV_TAG=$(git rev-parse --short HEAD~1)

cd infra/environments/{env}
terraform plan -var="app_image_tag=$PREV_TAG" -out=tfplan-rollback
terraform apply tfplan-rollback

Then verify the health check passes with the rolled-back version.

Checklist

Before deploying to prod:

• [ ] All tests pass (make test)
• [ ] Migrations are included and tested on staging
• [ ] No secrets are hardcoded (check with git diff --cached | grep -i secret)
• [ ] Health check endpoint returns expected fields
• [ ] Rollback plan is documented with the previous known-good tag

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Benja-Pauls
• Source: Benja-Pauls/SerpentStack
• License: MIT
• Homepage: https://www.npmjs.com/package/serpentstack

Install and usage instructions live in the source repository linked above.