deploy

name	deploy
description	Deploy CDK stacks and content to AWS environments Use when this capability is needed.
metadata	{"author":"finlaysonstudio"}

Deploy

How to deploy CDK infrastructure and application content to AWS.

Environments

Environment	Hostnames	AWS Account
sandbox	sandbox.jaypie.net, garden-api.sandbox.jaypie.net, garden.sandbox.jaypie.net	Finlayson Studio Sandbox (562880556342)
development	development.jaypie.net, garden-api.development.jaypie.net, garden.development.jaypie.net	Finlayson Studio Development (211125635435)
production	jaypie.net, garden-api.jaypie.net, garden.jaypie.net	Finlayson Studio Development (211125635435)

Stacks

Stack ID	Description
JaypieDocumentation	Documentation site (S3 + CloudFront)
JaypieGardenData	Shared DynamoDB table
JaypieGardenApi	Garden streaming API (Express Lambda)
JaypieGardenNextjs	Garden Next.js frontend

Remote Deploy (Preferred)

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

Branch Triggers

Branch Pattern	Deploys To	Lint/Test Required
feat/*, fix/*, branch/*, claude/*, sandbox/*	sandbox	No
main, development/*	development	Yes
(no branch trigger)	production	(tag only)

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

Tag Triggers

Tag Pattern	Deploys To	Lint/Test Required
sandbox-*	sandbox	No
development-*	development	Yes
stack-documentation-*	documentation only	No

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)

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):

   aws sso login --profile Developer-562880556342
   

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

   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-ui: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

Variable	Default	Description
AWS_PROFILE	(required)	AWS SSO profile name
AWS_REGION	us-east-1	AWS region
CDK_DEFAULT_ACCOUNT	(from STS)	AWS account ID
CDK_DEFAULT_REGION	us-east-1	CDK target region
CDK_ENV_HOSTED_ZONE	jaypie.net	Route53 hosted zone
PROJECT_ENV	sandbox	Environment identifier
PROJECT_KEY	jaypie	Project identifier
PROJECT_NONCE	local	Unique resource suffix
PROJECT_SPONSOR	finlaysonstudio	Organization name

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:

   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.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.