From Clone to a Running Stack: Deploying the SaaS Template on AWS
Deploying a fresh copy of the template to an empty AWS account: the exact steps, what broke, and what the test didn't cover.
I took a fresh copy of saas-backend-v2, renamed it and deployed it to an empty AWS account. It worked: the smoke tests passed 161 checks on the backend and 156 on the assistant. It only worked after six small fixes, though, and all of them are now in the repository.
This post gives you the exact steps, what broke on the way, and what the test didn't cover. If you're new to the template, start with what's in it and who it's for.
What you need
These steps create real AWS resources in your account, so use a dev or sandbox account and set a budget alert.
| You need | Why |
|---|---|
| An AWS account, with the AWS CLI signed in | Set AWS_PROFILE and AWS_REGION, because the smoke tests read the region from your session |
| AWS SAM CLI | Builds and deploys the stack |
uv and Python 3.13 | Installs the Python packages and runs the scripts |
Node.js 22 and pnpm | Builds the web app |
| A Stripe test key | Billing needs it, and the smoke test refuses a live key |
| An OpenRouter key | Only for the assistant, whose default model runs through OpenRouter |
The steps
These examples name the project acme, so use your own name throughout.
-
Copy the repository and rename it. This renames the packages, stacks, SSM parameters and event source, so two copies never collide in one account. The template is MIT-licensed: keep the
LICENSEnotice in your copy, and add your own beside it if you like.git clone https://github.com/henryonai/saas-backend-v2 acme && cd acme uv run python scripts/rename-project.py acme --title "Acme" uv sync --all-packages && (cd web && pnpm install) git diff # review, then commit -
Run the checks. None of them need an AWS account, so a failure here costs you nothing.
uv run pytest ./scripts/export-requirements.sh --check uvx ruff check . uvx cfn-lint template.yaml .github/deploy-role.yaml (cd web && pnpm gen:api && pnpm typecheck && pnpm lint && pnpm test && pnpm build) -
Put a Python with pip on your
PATH.sam buildneeds Python 3.13 with pip. The macOS Python and the project's.venvboth fail, so use uv's own Python, or runsam build --use-containerin step 5.export PATH="$(dirname "$(uv python find --system 3.13)"):$PATH" -
Store your Stripe test key. The command waits silently for you to paste the key and press Enter, so the key never appears in your shell history.
read -rs STRIPE_KEY && aws ssm put-parameter --name /acme/dev/stripe-secret-key \ --type SecureString --value "$STRIPE_KEY"; unset STRIPE_KEY -
Deploy the backend. This first deploy leaves out the assistant, because the assistant's code goes into a bucket that this deploy creates.
./scripts/export-requirements.sh && sam build sam deploy --config-env dev -
Set up Stripe. The script creates the prices, the customer portal and the webhook, then saves the webhook's signing secret in SSM. You don't create that secret yourself.
uv run python scripts/stripe-setup.py --stack acme-dev -
Publish the web app. It goes to the address in the stack's
WebUrloutput.(cd web && ./scripts/deploy.sh acme-dev) -
Run the smoke test. It creates three test users and calls every endpoint. It passed 161 checks on my copy.
uv run scripts/smoke-test.py --stack acme-dev -
Add the assistant, if you want it. Store the OpenRouter key, deploy again with the agent's code, and test it. This smoke test adds three more users and costs a few cents of model tokens. It passed 156 checks on my copy.
read -rs OPENROUTER_KEY && aws ssm put-parameter --name /acme/dev/openrouter-api-key \ --type SecureString --value "$OPENROUTER_KEY"; unset OPENROUTER_KEY sam deploy --config-env dev \ --parameter-overrides "$(uv run python scripts/package-assistant.py --config-env dev)" uv run scripts/smoke-assistant.py --stack acme-dev
That's a working stack. Open WebUrl and sign up. Stripe's test card, 4242 4242 4242 4242, works at checkout.
What broke on a clean copy
The application itself was fine. All six problems were in the setup scripts and instructions, in places I had stopped noticing because I never run them from zero.
| What went wrong | Why | What happens now |
|---|---|---|
| The rename script's next steps were wrong | They said to create a random webhook secret by hand, but stripe-setup.py writes that secret now | It prints the real steps, in order |
| The README's setup step led nowhere | It pointed to a webhook secret that its own section didn't describe | It lists the first deploy's commands |
sam build failed | It needs Python 3.13 with pip, and the macOS Python and .venv don't qualify | The README shows how to fix your PATH, or to use --use-container |
package-assistant.py crashed with a traceback | An account where sam deploy has never run has no bucket for the zip | It says to deploy once without the assistant, or to pass --bucket |
The smoke test's web check failed with AccessDenied | The web app hadn't been published yet | It says to run web/scripts/deploy.sh |
| The prod instructions were out of date | They still said to create the webhook secret | They say to store the Stripe key, and run stripe-setup.py after the first deploy |
Three of these came from the same change: billing moved to Stripe only, and the old setup instructions stayed behind. Tests can't catch that, because no test reads the README. If you publish a template, deploy it from an empty account before anyone else has to.
What this test didn't cover
I deployed from a terminal, to one dev stack. Three things are still unproven on a clean copy.
- The GitHub deploy workflow. I didn't create a new repository, so a new copy's deploy role, GitHub environments and
deploy.ymlweren't exercised. The workflow does run on the original repository, and the README's "CI/CD" section explains how to set it up. - Production. The two-run prod deploy and the canary rollback have run on the original repository's prod stack, but not on a clean copy.
- Someone else's machine. I ran this on my own setup, so you may find a seventh problem. If you do, please open an issue.
Cleaning up
Deleting the stack doesn't remove everything, on purpose: the template keeps data so that a mistake can't destroy it. My test stack is still running, so treat this as a checklist I haven't run yet. Before you delete the stack, empty the web and exports buckets, because CloudFormation can't delete a bucket that still has objects in it.
Delete these by hand afterward:
| What stays behind | Where |
|---|---|
| The DynamoDB tables | DynamoDB console |
| The Cognito user pool | Cognito console |
| The assistant's files and checkpoint buckets | S3 console |
| Your keys and the webhook secret | SSM Parameter Store, under /acme/dev/ |
| The test prices, portal configuration and webhook | Your Stripe dashboard, in test mode |
What's next
You now have a running stack, and the next posts show how to build on it: how multi-tenancy works here, how to build your first module, and how to add your own AI agent.