Infrastructure

Prerequisites

• Node.js 22+
• AWS account
• AWS CLI installed

Steps

1. Create deployment credentials

Create a dedicated IAM user for deployments so you are not using the AWS root account.

1. Sign in to the AWS Console and open IAM.
2. Go to Users → Create user.
3. Enter a name such as rawstack-deploy, then create the user.
4. Open the new user and create an access key for CLI use.
5. Save the Access key ID and Secret access key somewhere secure. AWS only shows the secret key once.
6. Attach the permissions needed to deploy CDK stacks and push Docker images to ECR:
   • attach the CDK-Assume-Bootstrap-Roles permission
   • create and attach a custom policy named Push-To-Ecr using the JSON below

Replace 123456789000 with your AWS account ID before saving the policy. You can find your account ID in the AWS Console account menu.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "EcrAuth",
			"Effect": "Allow",
			"Action": "ecr:GetAuthorizationToken",
			"Resource": "*"
		},
		{
			"Sid": "EcrReadForPull",
			"Effect": "Allow",
			"Action": [
				"ecr:BatchCheckLayerAvailability",
				"ecr:BatchGetImage",
				"ecr:GetDownloadUrlForLayer",
				"ecr:DescribeRepositories"
			],
			"Resource": "arn:aws:ecr:*:123456789000:repository/*"
		},
		{
			"Sid": "EcrWriteForPush",
			"Effect": "Allow",
			"Action": [
				"ecr:CreateRepository",
				"ecr:InitiateLayerUpload",
				"ecr:UploadLayerPart",
				"ecr:CompleteLayerUpload",
				"ecr:PutImage"
			],
			"Resource": "arn:aws:ecr:*:123456789000:repository/*"
		}
	]
}

After creating the user, configure the AWS CLI locally with the new access key:

aws configure

If you prefer to use a named profile, the flow looks like this:

aws configure --profile <PROFILE_NAME>

Use the same profile name for the CDK commands in the next steps.

2. Install dependencies

From the infrastructure package, install the project dependencies:

cd infrastructure/aws
npm install

3. Configure environment

Copy the example environment file:

cp .env.dist .env

Fill in the required values — see Infrastructure deployment for the full variable reference.

4. Bootstrap CDK

Bootstrap CDK in your AWS account and region before the first deployment. This is usually a one-time setup step per account/region.

cdk bootstrap

With a named profile:

cdk bootstrap --profile <PROFILE_NAME>

5. Create the API ECR repository and push the API image

The Core stack expects the API image to already exist in ECR. Create the repository first, then build and push the image from the repo root.

From infrastructure/aws:

set -a
source .env
set +a

aws ecr create-repository --repository-name "$CORE_ECR_REPOSITORY_NAME" --region "$AWS_REGION"
cd ../..
./scripts/push-api-to-ecr.sh
cd infrastructure/aws

With a named profile:

set -a
source .env
set +a
export AWS_PROFILE=<PROFILE_NAME>

aws ecr create-repository --repository-name "$CORE_ECR_REPOSITORY_NAME" --region "$AWS_REGION"
cd ../..
./scripts/push-api-to-ecr.sh
cd infrastructure/aws

Use CORE_ECR_REPOSITORY_NAME and AWS_REGION from your .env. Continue once the script finishes successfully and you can see the API image in ECR.

6. Optional: Create the Web ECR repository and push the Web image

If you plan to deploy the web stack, repeat the same process for the web image before running CDK deploy.

From infrastructure/aws:

set -a
source .env
set +a

aws ecr create-repository --repository-name "$WEB_ECR_REPOSITORY_NAME" --region "$AWS_REGION"
cd ../..
./scripts/push-web-to-ecr.sh
cd infrastructure/aws

With a named profile:

set -a
source .env
set +a
export AWS_PROFILE=<PROFILE_NAME>

aws ecr create-repository --repository-name "$WEB_ECR_REPOSITORY_NAME" --region "$AWS_REGION"
cd ../..
./scripts/push-web-to-ecr.sh
cd infrastructure/aws

Use WEB_ECR_REPOSITORY_NAME and AWS_REGION from your .env. Continue once the web image is visible in ECR.

7. Preview changes

Review the infrastructure changes before deploying:

npm run cdk diff

With a named profile:

AWS_PROFILE=<PROFILE_NAME> npm run cdk diff

8. Deploy all stacks

Deploy all infrastructure stacks:

npm run cdk deploy --all

With a named profile:

AWS_PROFILE=<PROFILE_NAME> npm run cdk deploy --all

Or deploy individual stacks:

npm run cdk deploy core
npm run cdk deploy web
npm run cdk deploy admin-hosting

The first deploy takes ~15–20 minutes as RDS and ElastiCache provision.

9. Optional: Destroy the stacks

When you're finished evaluating the project, destroy the stacks to avoid ongoing AWS charges.

npm run cdk destroy --all

With a named profile:

AWS_PROFILE=<PROFILE_NAME> npm run cdk destroy --all

Find out more about the infrastructure by reading the in-depth deep dive.