Skip to content
Serverless SaaS

Quick start

Prerequisites

Section titled “Prerequisites”
  • An AWS account and credentials with admin rights. aws sts get-caller-identity should work.
  • Node.js 20 or later, Python 3.12 or later.
  • Docker running. CDK uses it to bundle the Python Lambdas.

deploy.sh runs cdk bootstrap for you, so a fresh account and region work.

Deploy

Section titled “Deploy”

  1. Clone the repository and deploy everything. The email address becomes the first system admin, admin.

    Terminal window
    git clone https://github.com/buixuanhai/serverless-saas.git
    cd serverless-saas
    ./scripts/deploy.sh you@example.com

    This takes about 20 minutes. It deploys ControlPlaneStack, serverless-saas-bootstrap, serverless-saas-tenant-template-pooled and serverless-saas-tenant-pipeline, uploads the source bundle that provisioning and the pipeline use, then builds and deploys the web apps and these docs in serverless-saas-client.

  2. Set a permanent password for the system admin. Cognito also emails a temporary one, which the admin console will ask you to change on first sign-in.

    Terminal window
    ./scripts/admin-token.sh 'YourPassw0rd!' --set-password

  3. Onboard a tenant. Use the admin console or the script:

    Terminal window
    ADMIN_PASSWORD='YourPassw0rd!' ./scripts/onboard-tenant.sh acme admin@acme.example BASIC

    A pooled tenant is ready in about 2 minutes. A PLATINUM tenant takes about 8, because provisioning deploys a whole new stack.

  4. Open the apps. Their URLs are outputs of the serverless-saas-client stack:

    Terminal window
    aws cloudformation describe-stacks --stack-name serverless-saas-client \
      --query 'Stacks[0].Outputs[].[OutputKey,OutputValue]' --output table

    Sign in to AdminSiteUrl as admin. In AppSiteUrl, enter the tenant name acme and sign in with the tenant admin’s emailed temporary password.

Run the unit tests

Section titled “Run the unit tests”

The server tests use moto, so they need no AWS account.

Terminal window
cd server
python3 -m venv .venv && .venv/bin/pip install -r tests/requirements-test.txt
.venv/bin/python -m pytest tests -q

Deploy only the web apps

Section titled “Deploy only the web apps”

After changing the React apps or these docs:

Terminal window
DOMAIN_NAME=haibui.click ./scripts/deploy-client.sh

Leave out DOMAIN_NAME to use the default *.cloudfront.net hostnames. See Custom domain.

Clean up

Section titled “Clean up”
Terminal window
./scripts/cleanup.sh

This deletes every Platinum tenant stack, the client stack and all server stacks. The CDKToolkit stack is left in place.