Getting Started

This guide walks you through setting up a complete DevStride development environment. By the end, you'll have a running local dev server, a personal cloud stage, and a database branch — everything you need to start building.

Prerequisites

Before running ds setup, make sure the following tools are installed:

The Setup Walkthrough

Run the full automated setup:

ds setup

This kicks off a 10-step process that takes you from zero to a working environment. Here's what each step does:

Step 1: Pre-flight Checks

The CLI verifies that all required tools are installed and accessible. If anything is missing, it tells you exactly what to install and how.

Step 2: AWS SSO Authentication

You'll be prompted to authenticate with AWS via SSO. This opens a browser window where you confirm the login. The CLI waits for the SSO token to be issued, then continues.

Logging in to AWS SSO...
Opening browser for authentication...
✓ AWS SSO session established

Step 3: Access Verification

The CLI confirms you have access to:

• Pulumi Cloud — your infrastructure state backend
• DevStride organization — membership in the GitHub org

If either check fails, contact a team lead for access.

Step 4: Fetch Shared Secrets

Shared development API keys and configuration values are pulled from AWS Secrets Manager into your local .env file.

Pulling shared secrets to .env...
✓ 24 secrets written to .env

These include third-party API keys (Stripe, Pusher, Slack, Neon, GitHub), encryption keys, and other values needed for local development.

Step 5: Neon Database Branch

A personal PostgreSQL database branch is provisioned on Neon, forked from the main branch (which contains current staging data). Your DB_CONNECTION_STRING is automatically written to .env.

Creating Neon branch 'dev-phil-local'...
✓ Branch created, endpoint ready
✓ DB_CONNECTION_STRING updated in .env

This branch is tied to your fixed local stage (phil-local), not your git branch. Switching git branches does not affect your database.

Step 6: Install Dependencies

pnpm install

Installs all Node.js dependencies for the monorepo (backend, frontend, CLI, infrastructure).

Step 7: Pulumi Stack Initialization

A new Pulumi stack is created for your local stage. The stack name matches your local stage (e.g., phil-local).

Initializing Pulumi stack 'phil-local'...
✓ Stack created in Pulumi Cloud

Step 8: Deploy Infrastructure

The CLI runs pulumi up directly to provision all AWS resources for your personal stage:

Running pulumi up... (this may take 5-10 minutes)

✓ Infrastructure deployed successfully.
  API: https://api-phil-local.devstride.dev
  UI:  https://app-phil-local.devstride.dev

After provisioning, the CLI syncs Pulumi stack outputs to your local environment (bind cache) and pushes your configuration to Secrets Manager so the deployed Lambda functions can start.

Step 9: Run Database Migrations

Drizzle ORM migrations are applied to your Neon branch:

Running migrations...
✓ 47 migrations applied

Cognito test users are also seeded at this step so you can log in immediately.

Step 10: Build & Deploy Frontend

The Vue/Quasar frontend is built and uploaded to S3. CloudFront is invalidated so the latest build is served immediately.

Step 11: Save Setup State

Your developer name, AWS profile, region, and stage are persisted in ~/.devstride/setup-state.json so the CLI remembers your configuration across sessions.

Setup Options

You can customize the setup with flags:

# Specify your stage name upfront (skip the interactive prompt)
ds setup --stage phil-local

# Skip infrastructure deployment (useful if you only need local dev)
ds setup --skip-deploy

# Skip database migrations (run them manually later)
ds setup --skip-migrations

Verifying Your Environment

After setup completes, verify everything is working:

# List your deployed stage
ds deploy list

# Start local development
ds local run backend

What Setup Created

After a successful setup, you have:

Environment Variables

Setup configures these key environment variables:

DEVSTRIDE_STAGE is computed automatically by the ds wrapper as {DEVSTRIDE_DEVELOPER}-local. You do not set it manually. This fixed local stage ensures that switching git branches never affects your local environment.

Troubleshooting

"AWS SSO session expired"

The CLI auto-detects expired sessions and prompts re-login. If you see this during setup, follow the browser prompt to re-authenticate.

"Neon branch already exists"

If a branch with your stage name already exists, setup will reuse it and update your .env to point to it. No data is lost.

"Pulumi stack already exists"

If you've previously run setup for the same stage, the existing stack is reused. Run ds deploy up to update it.

Setup fails partway through

Setup is designed to be re-runnable. Simply run ds setup again — it will skip completed steps and resume where it left off.

Next Steps

• Developer Lifecycle — Day-to-day workflows and real-world scenarios
• Local Development — Running and debugging locally
• Database Management — Migrations, branches, resets