Deploy Your First Stage

Deploying a Stacktape stage takes your stacktape.ts configuration and provisions real AWS infrastructure — a CloudFormation stack containing every resource you declared. This page walks you through authentication, AWS account connection, and running your first deploy command.

Already deployed before? Skip to CI/CD or Going to production.

Prerequisites

Before deploying, you need:

  • A stacktape.ts configuration file (created in Configure your stack)
  • A Stacktape account (free — created during login)
  • An AWS account to deploy into

If you followed Use the dev mode, your config is already tested locally and ready for a real deployment.

Step 1: Log in to Stacktape

The stacktape login command authenticates your CLI with the Stacktape platform. The command verifies your credentials, saves the API key locally, and shows the authenticated user and organization.

stacktape login

The CLI opens an interactive auth flow. You can authenticate with Google, sign up with email, or enter an existing API key. After successful authentication, the CLI stores your credentials locally and displays your user and organization name.

For CI environments or headless servers where a browser is not available, pass an API key directly.

stacktape login --api-key YOUR_API_KEY

You can create API keys in the Stacktape Console.

Step 2: Connect your AWS account

Stacktape deploys resources into your own AWS account. Before your first deploy, you need to connect an AWS account to your Stacktape organization. This creates a cross-account IAM role that Stacktape assumes to perform deployments, read logs, and manage resources on your behalf.

Open the connected AWS accounts page in the Stacktape Console and click Connect AWS account. Enter an Account name (an arbitrary name like dev-account), then click Connect account in AWS console. This opens a CloudFormation Quick Create link in your AWS console. After the stack finishes creating, the connection activates automatically and the account status changes to ACTIVE in the Console.

Connecting an AWS account is free. AWS resources created by your stacks are billed by AWS in your AWS account.

What the connection creates

The connection CloudFormation stack must be created in the eu-west-1 region and creates an IAM role with cross-account trust. Stacktape assumes this role to deploy and manage resources in your account. Your actual project stacks can deploy to any AWS region — the connection stack location does not restrict where your infrastructure runs.

You can revoke access at any time by deleting the connection in the Console or deleting the CloudFormation stack directly in AWS. For details on the exact permissions granted, see AWS permissions.

Step 3: Deploy

With authentication and AWS connection in place, deploy your stack with the stacktape deploy command.

stacktape deploy --stage dev --region eu-west-1

Stages let you run multiple independent copies of your infrastructure — dev, staging, production — from the same configuration. See the stacktape deploy CLI reference for the full list of flags and their accepted values.

If your configuration file is not named stacktape.ts or is in a different directory, point the CLI at it explicitly.

stacktape deploy --stage dev --region eu-west-1 --config ./infra/stacktape.ts

What happens during deploy

Stacktape processes your configuration in four phases:

1

Build & Package

Bundles your application code (Lambda zips, container images), resolves resource configuration, evaluates directives and secrets, and generates the CloudFormation template.

2

Upload

Packaged artifacts are uploaded to an S3 deployment bucket in your AWS account.

3

Deploy

A CloudFormation stack is created (first deploy) or updated with the generated template. CloudFormation provisions, updates, or removes AWS resources as needed.

4

Post-deploy

For stacks that include hosting buckets or CDNs, Stacktape syncs static files and invalidates CDN caches. Then it prepares deployed stack information and resource links.

On the first deploy, CloudFormation creates the stack and all resources from scratch. On subsequent deploys, Stacktape prepares the CloudFormation template, computes a diff, uploads artifacts, and submits the template to CloudFormation to update the stack. When only code changed, Stacktape updates the changed Lambda functions or container services directly instead of running a CloudFormation stack update.

Deploy output

After a successful CLI deploy, Stacktape includes resource links and a Console URL in the completion output. The Console URL follows the pattern:

https://console.stacktape.com/projects/{project}/{stage}/overview

The Console URL includes the project name. The project name is set via --project, a configured default (see stacktape defaults set), or an interactive prompt on your first deploy. See the stacktape deploy CLI reference for the full list of flags. Open this URL to manage the deployed stack in the Console.

What gets created in AWS

A standard Stacktape deploy creates or updates a CloudFormation stack in the connected AWS account. When only code changed, Stacktape updates Lambda function code or container services directly without a CloudFormation stack update. The CloudFormation stack is the unit Stacktape manages for the stage. Inside the stack, CloudFormation provisions whatever your configuration declares:

WhatExample
Your declared resourcesLambda functions, container services, databases, buckets, queues — everything in your stacktape.ts
Deployment artifactsUploaded before the stack is deployed; Stacktape passes the CloudFormation template URL to CloudFormation
IAM roles and policiesResource access configured through connectTo; see Connecting resources for details
Log groupsCloudWatch log groups for each compute resource that produces logs

Because Stacktape deploys through CloudFormation, the resulting AWS resources also appear in the AWS console for direct inspection.

Verifying the deploy

After the deploy completes, verify your stack is running.

Open the resource URL printed by the CLI. For a web service or Lambda function with an HTTP trigger, this is a live HTTPS endpoint you can hit immediately.

The deploy output also includes a Console URL for the deployed stack. See Manage your app in the Console for what you can do there.

To view logs from the CLI, use stacktape logs.

stacktape logs

Redeploying after changes

After making code or configuration changes, run the same deploy command again.

stacktape deploy --stage dev --region eu-west-1

Stacktape prepares the CloudFormation template, computes a diff, uploads artifacts, and submits the template to CloudFormation to update the stack.

Code-only changes deploy in seconds

When a deployment changes only the code of functions or container services, Stacktape updates them directly instead of through CloudFormation. You don't need a flag for this. Changes to infrastructure or configuration always go through CloudFormation, and --full forces it. See Fast deployments.

Deploying multiple stages

Stages are independent copies of your infrastructure. Deploy a staging environment alongside dev by choosing a different stage name.

stacktape deploy --stage staging --region eu-west-1

Each stage is deployed as its own CloudFormation stack with its own resources and URLs. Use different stage names to run separate copies of the resources declared by your configuration. This lets you test changes in staging without affecting production users. For automated stage-per-branch workflows, see Stacks per git branch.

Troubleshooting

"No connected AWS accounts"

You need to connect an AWS account before deploying. Open the connected AWS accounts page in the Stacktape Console and follow the connection flow described in Step 2.

"belongs to AWS account …, which is not connected"

--profile, AWS_PROFILE or AWS keys in your environment point to an AWS account that is not connected to your organization. Stacktape deploys to the account your local AWS credentials belong to. Unset them, pass --aws-account <name>, or connect that account. See Choosing the account for a CLI command.

Deploy takes longer than expected

First deploys take longer because every resource must be created from scratch. Databases and container services take longer to provision than Lambda functions. Subsequent deploys that only change code take seconds, because Stacktape updates the code directly.

A resource fails to create

If a resource fails to create, the resources that were already created stay, and the stack is left in CREATE_FAILED. Fix the error and deploy again to continue from there, or run stacktape delete to remove everything. The CLI displays the specific error. Common causes include IAM permission issues, resource limit quotas, or invalid configuration values. For rollback options, see stacktape rollback for version-based rollback and stacktape stack recover for CloudFormation-level rollback.

Deploy fails during dev mode

You cannot deploy to a stage that currently has an active dev mode session. Stop dev mode first with stacktape dev stop, or deploy to a different stage name.

Deploy Your First Stage FAQ

How long does a first deploy take?

First deploys depend on the resources being provisioned. Lambda-only stacks are the fastest. Stacks with databases, container services, or custom domains take longer because AWS provisions those resources sequentially. Subsequent deploys that only change application code are faster since CloudFormation only updates the diff — and code-only changes skip CloudFormation entirely.

Does Stacktape cost money to use with AWS?

Connecting an AWS account is free. AWS resources created by your stacks are billed by AWS in your AWS account. See Billing and subscription for Stacktape plan details.

Can I deploy to any AWS region?

Yes. The AWS account connection stack is created in eu-west-1, but your project stacks can deploy to any AWS region. Specify the region with --region on each deploy command, or set a default with stacktape defaults set.

Is the connection between Stacktape and my AWS account secure?

The connection uses a CloudFormation stack that grants Stacktape cross-account AssumeRole access — the standard AWS approach for third-party integrations. You can revoke access instantly by deleting the connection stack in AWS or removing the account from the Console.

What happens if I lose internet during a deploy?

CloudFormation continues the deployment on AWS's side regardless of your local connection. If the CLI disconnects, check the stack status with stacktape status before running another deploy.

What's the difference between stages and AWS accounts?

Stages are logical environments (dev, staging, production) within a single AWS account — each stage gets its own CloudFormation stack with fully isolated resources. You can also connect multiple AWS accounts in the Console and deploy different stages to different accounts (e.g., production in a separate account). See Connecting your AWS account for details.

Can I preview what a deploy will change before running it?

Yes. Use stacktape diff to see the CloudFormation change set without actually deploying. This shows which resources would be created, updated, replaced, or deleted.


What does the CLI send to Stacktape?

The CLI sends usage statistics and reports of its own crashes, so we can see which commands fail and fix them. Set STP_DISABLE_TELEMETRY=1 to turn both off.

  • After every command: the command name, the names of the options you used (not their values), how long it took, whether it succeeded, the error code if it failed, your operating system, locale, time zone and the CLI version.
  • When the CLI crashes: the error type, message and stack trace, the command, your operating system, CPU architecture and whether it ran in CI. The CLI prints an error ID you can give our support. Errors in your configuration, code or AWS account are not reported this way; only failures of the CLI itself are.
  • Identity: a random ID of your machine. After stacktape login, events are linked to your Stacktape user and organization, and your account's email and name are attached to your user.

Before a crash report leaves your machine, the CLI masks tokens and other credentials, email and IP addresses, AWS account IDs and the user name in home-directory paths. Error messages can still contain other text, such as file or resource names. The CLI never sends configuration values, source code, environment variables or AWS credentials. Stacktape processes this data in PostHog in the EU.