Deploy

How to deploy CDK infrastructure and application content to AWS.

Environments

Stacks

Remote Deploy (Preferred)

Deployments trigger automatically via GitHub Actions. Push or tag to trigger.

Branch Triggers

Path filter: Only triggers when workspaces/**, .github/actions/**, or .github/workflows/deploy-*.yml change.

Tag Triggers

Manual Trigger

Use the Deploy Stacks (Manual) workflow via GitHub Actions UI or CLI:

# Deploy all stacks to sandbox
gh workflow run deploy-stacks.yml -f environment=sandbox -f stacks=all

# Deploy specific stack(s)
gh workflow run deploy-stacks.yml -f environment=sandbox -f stacks="JaypieGardenData"
gh workflow run deploy-stacks.yml -f environment=sandbox -f stacks="JaypieGardenData JaypieGardenApi JaypieGardenNextjs"

# Deploy to production
gh workflow run deploy-stacks.yml -f environment=production -f stacks=all

Quick Deploy via Tags

# Deploy to sandbox now
git tag sandbox-$(date +%s) && git push origin sandbox-$(date +%s)

# Deploy to development
git tag development-$(date +%s) && git push origin development-$(date +%s)

# Deploy to production
git tag production-$(date +%s) && git push origin production-$(date +%s)

Local Deploy

Local deploys go to sandbox only. Requires AWS SSO login and .env configuration.

Prerequisites

1. AWS SSO Login (ask user before running — correct browser must be in foreground):

   bashCopy

   aws sso login --profile Developer-562880556342
   

2. .env file at repo root with at minimum:

   Copy

   AWS_PROFILE=Developer-562880556342
   

Local Deploy Scripts

# Deploy individual stacks (sandbox only)
npm run deploy:documentation:sandbox
npm run deploy:garden-api:sandbox
npm run deploy:garden-nextjs:sandbox

Manual CDK Deploy

For stacks without scripts (e.g., JaypieGardenData) or custom scenarios:

# Set environment
export AWS_PROFILE=Developer-562880556342
export AWS_REGION=us-east-1
export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --profile $AWS_PROFILE --query 'Account' --output text)
export CDK_DEFAULT_REGION=$AWS_REGION
export CDK_ENV_HOSTED_ZONE=jaypie.net
export PROJECT_ENV=sandbox
export PROJECT_KEY=jaypie
export PROJECT_NONCE=local
export PROJECT_SPONSOR=finlaysonstudio
export PROJECT_VERSION=$(node -p "require('./package.json').version")

# Build and deploy
npm run build
cd workspaces/cdk
npx cdk deploy JaypieGardenData --profile $AWS_PROFILE --require-approval never -c stacks=JaypieGardenData

Environment Variables Reference

Monitoring Deployments

Check Workflow Status

# List recent workflow runs
gh run list --limit 5

# Watch a running workflow
gh run watch

# View a specific run
gh run view <run-id>

# View failed run logs
gh run view <run-id> --log-failed

Check Deployed Stacks in AWS

Use mcp__jaypie__aws with the appropriate profile:

aws("cloudformation_describe_stack", { stackName: "JaypieGardenData", profile: "Developer-562880556342" })
aws("dynamodb_describe_table", { tableName: "<table-name>", profile: "Developer-562880556342" })
aws("lambda_list_functions", { functionNamePrefix: "garden", profile: "Developer-562880556342" })

CloudFormation Stack Naming

Deployed stacks follow this pattern:

cdk-${PROJECT_SPONSOR}-${PROJECT_KEY}-${PROJECT_ENV}-${PROJECT_NONCE}-${resource}

Example: cdk-finlaysonstudio-jaypie-sandbox-local-garden-data

After Deploying

1. Monitor the workflow — use gh run watch or check GitHub Actions
2. On failure — delegate the failing run to a subagent to parse logs:
   Copy

   gh run view <run-id> --log-failed
   

3. Fix errors — even those that seem unrelated (lint, test, typecheck). Push fixes and re-monitor
4. Iterate — repeat until the workflow succeeds
5. Verify — check that stacks exist in AWS and resources are healthy

Troubleshooting

SSO Session Expired

aws sso login --profile Developer-562880556342

Ask the user first — they need the Finlayson Studio browser in the foreground.

Stack Deploys to Wrong Hostname

PROJECT_ENV is not set correctly. Ensure the GitHub environment has the right PROJECT_ENV value.

"Stack does not exist" in CloudFormation

The stack hasn't been deployed yet. Deploy it via GitHub Actions or locally.

"undefined" in Stack Name

A required environment variable is missing. Check all PROJECT_* and CDK_* variables.

Cross-Stack Dependencies

JaypieGardenData must be deployed before JaypieGardenApi or JaypieGardenNextjs if they consume the shared table. Deploy data stack first, then consumer stacks.