Getting started

Everything you need to go from purchase to a deployed app. This page orients you; the complete, authoritative runbook lives in the repository’s README.

1. Get access to the code

After your purchase, we invite the GitHub account you entered at checkout to the private cdkbase/cdkbase repository as a read-only collaborator. Accept the invitation — check your GitHub notifications or email, or open github.com/cdkbase/cdkbase/invitations — then clone it:

git clone https://github.com/cdkbase/cdkbase.git my-app
cd my-app

Entered the wrong GitHub username at checkout? Email support@cdkbase.com and we’ll re-send the invite.

2. What you’ll need

• An AWS account (one is enough to start; separate dev and prod accounts are recommended — set up in step 3).
• Node.js 22 and pnpm.
• The AWS CLI v2.
• A domain name you own. cdkbase creates a Route 53 hosted zone and TLS certificates for it and serves every app on it (the apex plus subdomains). Register it anywhere and delegate it — or a subdomain — to Route 53; one domain covers all environments.

3. Set up AWS

cdkbase deploys to one AWS account per environment, selected by an AWS profile, and signs in with AWS IAM Identity Center (SSO). The recommended structure is an AWS Organization with distinct roles: a management account that administers access and provisions the others (you don’t run your app here), plus a separate member account for each environment — dev and prod — where cdkbase actually deploys. So a realistic setup is the management account plus one or two member accounts. From scratch:

1. Create your management account. Sign up for an AWS account with a dedicated email. This becomes your organization’s management account — you administer access from here and generally don’t deploy app resources into it.
2. Enable IAM Identity Center. In the AWS console, open IAM Identity Center and enable it (choose a home region). This automatically turns on AWS Organizations and gives you a sign-in start URL, like https://d-xxxx.awsapps.com/start.
3. Create a member account for each environment. In AWS Organizations → Add an AWS account → Create an AWS account, create one for dev and one for prod — these are where cdkbase deploys. Each needs its own email; a “+” alias such as you+cdkbase-prod@example.com works. You don’t have to create both up front — start with one and add the other later.
4. Grant yourself access. In IAM Identity Center, create a permission set (for example, AdministratorAccess) and a user for yourself if you don’t already have one, then assign that user to the dev and prod accounts with the permission set.
5. Sign in locally. Run aws configure sso --profile <env> for each environment — the profile name must match the env key you choose in the setup wizard — using your start URL, then pick the matching account and role.

4. Configure your fork

Run the setup wizard. It asks for each environment’s AWS profile name, account ID, root domain, and data-protection setting, then writes your local config and installs dependencies:

pnpm run setup

This creates your private cdkbase.config.ts (gitignored), so pulling future template updates never collides with your real account and domain values. The profile names you used in step 3 should match the env keys here.

5. Deploy

At a glance — the README has the full, ordered runbook including the DNS handoff:

export AWS_PROFILE=my-app-dev          # selects the environment
pnpm run sso                          # aws sso login
pnpm --filter infra run cdk:bootstrap # one-time per account/region
pnpm run deploy                       # builds frontends + cdk deploy --all

The first thing deployed is the DNS stack — the Route 53 hosted zone and TLS certificates — and it pauses for a one-time handoff: copy the four nameservers it prints to your registrar (or parent zone) and wait for delegation to propagate so the certificates can validate. The deploy then resumes and brings up everything else. After that, run the database migrations and sign up your first user — both covered step-by-step in the README.

6. Work with Claude Code

cdkbase ships a Claude Code skill (an operating manual the agent reads) and MCP servers. Open the repo in Claude Code and it can deploy stacks, query your database, and extend the app for you from the first session. The skill lives at .claude/skills/cdkbase/SKILL.md.

It also comes preconfigured with a set of AWS Labs MCP servers (AWS docs, CDK, Lambda, DSQL, and more) in .mcp.json, so Claude can reference authoritative AWS documentation and tooling as it works. Setup notes for those are in the repo.

7. Make it yours

• Remove a feature by deleting its stack file (infra/lib/<name>-stack.ts), its line in bin/infra.ts, and its apps/ or services/ folder — there are no runtime feature flags to untangle.
• Add a billing tier, a service, a frontend, or an environment by following the patterns documented in the README and the skill.
• Turn on Stripe billing with your own keys when you’re ready — see the Stripe section of the README.

Where the full docs live

• README — the complete setup and deploy runbook, in the repo root.
• .claude/skills/cdkbase/SKILL.md — the operating manual: architecture, conventions, gotchas, and how to add things.
• The live demo — auth, todos, and billing running on this same stack.

Need help?

Email support@cdkbase.com.