vk deploy

Usage

vk deploy [options]

Options

Option	Description	Default
-s, --stage <stage>	Stage name (dev, stage, prod)	dev
--allow-rollback	Force CloudFormation rollback on failure, overriding the --no-rollback default used on stage/prod. Required for deploys that include replacement-type property changes on a stack last left in UPDATE_FAILED by a --no-rollback deploy. Implies CDK --force so a stack paused in CREATE_FAILED/UPDATE_FAILED is rolled back without an interactive prompt	off
--skip-typecheck	Skip the pre-deploy tsc --noEmit gate (emergency deploys only)	typecheck runs

Description

Deploys your VentureKit application to AWS via CDK. The stage determines which environment config is used:

Stage	Config File	Typical Preset
dev	config/dev.ts	free or nano
stage	config/stage.ts	micro
prod	config/prod.ts	medium or large

Examples

# Deploy dev (default)
vk deploy

# Deploy staging
vk deploy --stage stage

# Deploy production
vk deploy --stage prod

Production Warning

When deploying to prod or production, the CLI displays a warning:

⚠️  Production deployment - please verify your changes

Outputs

After a successful deployment, the CLI shows:

• The deployed stage name
• The API Gateway URL (if available)

✅ Deployed to prod
API URL: https://abc123.execute-api.eu-west-1.amazonaws.com

Auto-Bootstrap

On first deploy, vk deploy automatically sets up the AWS environment (CDK bootstrap). You never need to run cdk bootstrap manually. If the bootstrap stack is missing, VentureKit handles it transparently:

🚀 Deploying to dev...

✔ Infrastructure template ready
  Setting up AWS environment (first-time setup)...
✔ AWS environment ready
✔ Deployed successfully!

If bootstrap fails, the CLI provides actionable guidance (e.g. missing AWS credentials).

Type-check gate

Before touching AWS, vk deploy runs tsc --noEmit against the project (routes, functions, vk.config.ts) whenever a tsconfig.json exists. A half-applied CloudFormation deploy is far more expensive to unwind than a local compile, so type errors abort the deploy. --skip-typecheck bypasses the gate for emergencies; vk check runs the same check on its own.

Pre-flight

After the type-check, vk deploy resolves what the template needs from your AWS account and inspects every tier stack before synthesising:

• Custom-domain certificates — for each domains[] entry on external DNS without a certificateArn, it finds the ACM certificate already covering the name or requests a DNS-validated one, prints the validation CNAMEs (same table as vk cert request), and injects the ARN once ACM reports ISSUED. A domain still waiting on validation is skipped for this deploy — the API stays reachable on its execute-api URL.
• Shared SES identities — for each notify[] intent it asks SES whether the domain identity already exists and whether this venture’s messaging stack created it; an identity another venture owns is treated as sesIdentity: 'shared' for the synth (see Notify Intent).
• Stack state recovery — every tier stack (<project>-<stage>-network|data|identity|config|messaging|edge|app) is probed and dispatched on its status:
  • *_IN_PROGRESS (a second push while the previous deploy still runs, or a cancelled CI job whose operation kept going) is waited out — up to 45 minutes — instead of failing the run.
  • ROLLBACK_COMPLETE, ROLLBACK_FAILED and REVIEW_IN_PROGRESS are never-created debris and are deleted before deploying fresh — unless the stack still holds live stateful resources (DELETE_SKIPPED retained resources), in which case the deploy stops and tells you.
  • UPDATE_ROLLBACK_FAILED gets an automatic ContinueUpdateRollback; only if that fails too do you get the printed --resources-to-skip command.
  • CREATE_FAILED, UPDATE_FAILED, UPDATE_ROLLBACK_COMPLETE and IMPORT_ROLLBACK_COMPLETE (a previous deploy undone or half-applied) deploy with --import-existing-resources so CloudFormation adopts RETAIN-policy resources it stranded instead of failing on the name. This covers Add actions only — a replacement under a new physical name is not adoptable.

Rollback policy

Stage and prod deploys run CDK with --no-rollback: a failed update pauses at the failure point (UPDATE_FAILED) instead of rolling back — so the retry resumes where it stopped and you never land in the unrecoverable UPDATE_ROLLBACK_FAILED. Two consequences:

• --no-rollback cannot deploy a replacement. When a change set contains one, vk deploy passes CDK --force automatically whenever stdin is not a TTY (CI), so the deploy downgrades to a normal rollback-enabled run instead of dying on TtyNotAttached. Locally you are prompted. Note that a mid-replacement failure will then re-strand RETAIN resources.
• --allow-rollback forces the rollback behaviour explicitly (and implies --force).

Transient-failure retries

Some CloudFormation failures are retried automatically, scoped strictly to the deploying project’s <project>-<stage>-* stack family (up to 3 retries, i.e. 4 attempts):

• CloudWatch Logs create race — AWS::Logs::LogGroup “The specified log group does not exist” when many log groups are created in parallel. The app stack also serialises log-group creation (two lanes per nested stack) to make the race rare in the first place.
• Stranded log groups — on strict-retain stages a deploy that failed after creating log groups leaves them behind owned by no stack, and every later deploy fails with AlreadyExists. vk deploy parses the blocked names, deletes the ones it can prove are its own leftovers (the aws:cloudformation:stack-name tag still points at the stack being deployed; untagged groups only when provably unwritten — zero bytes and zero streams) and retries. Anything else is left alone with the exact aws logs delete-log-group commands printed for review.

Under the Hood

1. Loads your vk.config.ts and resolves the environment config for the stage
2. Type-checks the project (tsc --noEmit) unless --skip-typecheck
3. Auto-installs missing deploy dependencies — aws-cdk-lib + constructs, and the aws-cdk CLI as a devDependency (^2.170.0) so the toolchain is pinned rather than downloaded fresh by npx on every CI run
4. Runs the pre-flight above (certificates, SES identities, stack states)
5. Generates a multi-stack CDK app in .vk/cdk/ — one CloudFormation stack per tier: network, data, identity, config, messaging, edge, app (only the tiers your intents activate)
6. Checks if the AWS environment is bootstrapped; if not, runs bootstrap automatically
7. Runs cdk deploy (with --no-rollback on stage/prod and --import-existing-resources when adopting) to synthesize and deploy the stacks
8. Creates or updates Lambda functions, API Gateway, and all declared infrastructure

All CDK complexity is hidden — you never interact with CDK directly.