Deployment Guide¶

Full Deployment¶

The full deployment pipeline is run via:

pnpm deploy:all

This executes scripts/deploy.sh which performs:

flowchart TD
    A["1. Generate Sentry release version"] --> B["2. Run tests (pnpm test)"]
    B --> C["3. Build all packages (pnpm build)"]
    C --> D["4. Build Lambdas (pnpm build:lambdas)"]
    D --> E["5. Create Sentry releases<br/>(web, homepage, desktop, lambdas)"]
    E --> F["6. Associate git commits"]
    F --> G["7. Upload source maps"]
    G --> H["8. Deploy web (Cloudflare Pages)"]
    G --> I["9. Deploy homepage (Cloudflare Pages)"]
    G --> J["10. Deploy infrastructure (CDK)"]
    G --> K["11. Package desktop (Tauri)"]
    H & I & J & K --> L["12. Finalize Sentry releases"]

Prerequisites¶

Requirement	How to Set Up
AWS CLI + profile	`aws configure --profile bytes-and-books`
Cloudflare Wrangler	`npx wrangler login`
Sentry CLI	Installed via `@sentry/cli` dev dependency
Environment variables	See Configuration Guide

Individual Component Deployment¶

Web Portal¶

pnpm build:web
cd apps/web && pnpm deploy

Deploys to Cloudflare Pages project task-and-time-portal. Build output is in apps/web/dist/.

Homepage¶

pnpm build:homepage
cd apps/homepage && pnpm deploy

Deploys to Cloudflare Pages project bytes-and-books-homepage. Build output is in apps/homepage/dist/.

Infrastructure (AWS)¶

pnpm build:lambdas
cd infrastructure && pnpm cdk deploy

Uses AWS profile bytes-and-books. Deploys API Gateway, Lambda functions, DynamoDB tables, Cognito, and EventBridge rules.

Before deploying, you can preview changes:

cd infrastructure && pnpm cdk diff

Desktop App¶

pnpm package:desktop

Builds the Tauri desktop application for the current platform.

Documentation¶

pnpm docs:deploy

Builds MKDocs and deploys to Cloudflare Pages project task-time-docs.

Sentry Release Lifecycle¶

Each deployment creates Sentry releases for 4 projects:

Sentry Project	Source
`SENTRY_PROJECT_WEB`	Web portal
`SENTRY_PROJECT_HOMEPAGE`	Homepage
`SENTRY_PROJECT_DESKTOP`	Desktop app
`SENTRY_PROJECT_LAMBDAS`	Lambda functions

The lifecycle:

Create release with version from sentry-cli releases propose-version
Associate commits from git history
Upload source maps for each project
Finalize release after all deploys complete

Rollback Procedures¶

Web Portal / Homepage¶

Cloudflare Pages maintains deployment history. To rollback:

Go to Cloudflare Dashboard → Pages → select project
Click on Deployments
Find the previous working deployment
Click "Rollback to this deployment"

Infrastructure (AWS)¶

CDK doesn't have a built-in rollback command. Options:

Revert code and redeploy: git revert the problematic commit, then cdk deploy
CloudFormation console: Go to CloudFormation → select stack → Stack actions → Rollback
Lambda versions: If only Lambda code changed, you can update the function code from a previous build artifact

Warning

DynamoDB table schema changes (new GSIs, key changes) may not be easily reversible. Always use cdk diff before deploying.

Desktop App¶

Distribute the previous build artifact to users. Desktop apps are self-contained binaries.

Troubleshooting¶

Common Issues¶

CDK deploy fails with "no credentials" : Ensure AWS profile bytes-and-books is configured: aws configure --profile bytes-and-books

Cloudflare Pages deploy fails : Run npx wrangler login to refresh authentication

Lambda timeout errors after deploy : Check Lambda environment variables are correctly set. Missing env vars can cause silent failures.

CORS errors in browser : Verify API Gateway OPTIONS routes exist and CORS headers are set on gateway responses. Run cdk diff to check.

Sentry source maps not working : Ensure SENTRY_AUTH_TOKEN has project:releases scope and release version matches between build and Sentry.