Getting Started

This guide walks through bootstrapping a local DevStride development environment from a clean checkout. There is no single onboarding command that does this for you — it's a short, one-time sequence of shell config, AWS SSO setup, and a hand-filled .env file, followed by two commands (ds run backend and ds run ui) that you'll use every day after that.

Prerequisites

Bootstrap Sequence

Do this once, in order, from the repo root.

1. Set your shell environment variables

Add to your shell config (e.g. .zshrc):

export DEVSTRIDE_STAGE=${your_name}              # e.g. phil
export DEVSTRIDE_DEV_PROFILE=devstride-${your_name}  # e.g. devstride-phil
export DEVSTRIDE_REGION=eu-central-1              # or whichever region is nearest you

export AWS_CONFIGURE_SSO_DEFAULT_SSO_START_URL=https://devstride.awsapps.com/start
export AWS_CONFIGURE_SSO_DEFAULT_SSO_REGION=us-east-1

sso(){
  unset AWS_PROFILE
  export AWS_PROFILE=$1
  aws sts get-caller-identity &> /dev/null || aws sso login || (unset AWS_PROFILE && aws-configure-sso-profile --profile $1)
  eval $(aws-export-credentials --env-export)
}

alias ds='./ds'

DEVSTRIDE_STAGE becomes the name of your own personal cloud stage — every developer deploys to their own isolated stage, keyed off this value.

2. Set up AWS SSO

Install the AWS CLI v2, then configure SSO with the same profile name as DEVSTRIDE_DEV_PROFILE:

aws configure sso

SSO start URL [None]: https://devstride.awsapps.com/start
SSO Region [None]: us-east-1
# after logging in via the browser:
CLI default client Region [None]: eu-central-1   # nearest region for you
CLI default output format [None]: json
CLI profile name [AWSAdministratorAccess-xxxxxxxxxxxx]: devstride-${your_name}

Then install the two helper packages SST needs to consume SSO credentials:

pip3 install aws-sso-credential-process
pip3 install aws-export-credentials

3. Install Node 22 and pnpm

nvm install 22
nvm alias default 22
nvm use 22

corepack enable
pnpm install

4. Fill in your .env file

Copy the sample and fill in real values by hand:

cp .env.sample .env

.env.sample lists the following, all needing real values before the app will run correctly:

5. Generate an ENCRYPTION_KEY

ENCRYPTION_KEY must be exactly 32 bytes (64 hex characters) — it's used to encrypt sensitive data such as database credentials in transit:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Paste the result into .env as ENCRYPTION_KEY. Never commit this value — each environment should have its own unique key.

6. First deploy: ds run backend

ds run backend

This is both how you run the backend day-to-day and how your personal SST stage gets created the first time — ds run backend runs pnpm install, cleans up any orphaned CloudFormation stacks, then runs pnpm exec sst dev, which provisions your stage's AWS resources on first run. Once it finishes deploying, stop it (Ctrl+C) — you need to run migrations and push config before it's actually usable.

7. Run database migrations

ds migrations run

8. Push your config: ds script set-config

ds script set-config

This reads your local .env, validates that every required variable is set (DB connection strings, Stripe, OpenAI, GitHub App, Pusher, Slack, encryption key, and more), and pushes them up into an SST DEVSTRIDE_CONFIG secret (base64-encoded JSON) that your running Lambda / sst dev process reads at runtime.

9. Set up Stripe (test mode)

Ask a teammate to set up a Stripe test account for you, then:

1. Grab the secret key from the Stripe test API keys page and set STRIPE_SECRET_KEY / STRIPE_PUBLIC_KEY in .env.
2. Add a webhook endpoint at https://api.{stage}.devstride.dev/v1/subscriptions/stripe/webhooks, listening for customer.subscription.created, customer.subscription.deleted, customer.subscription.trial_will_end, and customer.subscription.updated. Copy the signing secret into STRIPE_WEBHOOK_SECRET.
3. Re-run ds script set-config so the updated values are pushed up.
4. Seed Stripe products:

ds stripe add-products

Daily Use

Once bootstrapping is done, this is all you run day to day, in two terminal tabs:

ds run backend

ds run ui

ds run backend starts SST's live-lambda dev mode against your personal stage. ds run ui spawns the Vite dev server in frontend/, wired up with VITE_* env vars derived from your bound stage.

Running the Test Suite

The backend test suite needs Docker for a local DynamoDB — this is the only place Docker is required:

docker pull amazon/dynamodb-local
cd backend && pnpm test

Next Steps

• Local Development — Running and debugging locally day-to-day
• Introduction to the ds CLI — How ./ds resolves and runs a command
• Command Reference — Every ds command, organized by category