Deployment Guide

This guide explains the deployment architecture, workflows, and processes for the Wrkbelt platform.

Environments Overview

Wrkbelt uses a multi-environment deployment strategy to ensure code quality and stability:

Environment	Purpose	Deployment Method	Current Status
Develop	Feature testing and integration	Automatic	Disabled until V0.0.1 release
Staging	Pre-release validation	Automatic	Active
Production	Live environment	Manual approval	Active

Architecture Overview

The Wrkbelt platform is deployed using a hybrid architecture with services spread across multiple cloud platforms:

Deployment is divided into four main pipelines:

1. API Services: Deployed to AWS using GitHub Actions and AWS Copilot
2. WWW Marketing Site: Deployed to AWS using GitHub Actions with SST and OpenNext
3. UI Application: Deployed to AWS using GitHub Actions with SST and OpenNext
4. Support Applications: Deployed to Netlify (Dev-Docs, Storybook)

API Deployment

The API services are containerized and deployed to AWS using Copilot orchestration.

API Deployment Flow

API CI/CD Configuration

The API deployment is controlled by GitHub Actions workflows:

1. Automatic Deployments (cicd-api.yml):

   • Triggered on push to main/develop branches
   • Only runs when relevant files change
   • Automatically deploys to staging/develop environments

2. Production Deployment (deploy-prod-api.yml):

   • Manually triggered workflow
   • Requires explicit confirmation ("yes" input)
   • Deploys to production environment

API Environment Variables

API environment variables are managed through .env files stored in S3:

The workflow automatically selects the correct .env file based on the target environment.

API Production Deployment

Deploying to production requires manual approval:

1. Navigate to the GitHub repository Actions tab
2. Select "Prod API CI/CD Pipeline" workflow
3. Click "Run workflow"
4. Type "yes" in the confirmation field
5. Click "Run workflow" to begin deployment
6. Monitor the workflow logs for deployment status

Frontend Applications Deployment

The platform includes two frontend applications deployed to AWS using SST and OpenNext, plus supporting applications deployed to Netlify.

Domain Architecture

The platform uses a multi-domain architecture to separate concerns:

Domain Pattern	Application	Purpose	Example
www.{env}.wrkbelt.com	WWW	Marketing site	www.wrkbelt.com
{env}.wrkbelt.com	WWW	Apex redirect	wrkbelt.com → www.wrkbelt.com
app.{env}.wrkbelt.com	UI	Web application	app.wrkbelt.com
*.{env}.wrkbelt.com	UI	Scheduler embeds	client-name.wrkbelt.com

Where {env} is empty for production, or staging/develop for other environments

WWW Marketing Site

The WWW marketing site serves the public-facing website and handles all marketing content, landing pages, and public information.

Domain Ownership:

• Production: www.wrkbelt.com (apex wrkbelt.com redirects to www)
• Staging: www.staging.wrkbelt.com (apex staging.wrkbelt.com redirects to www)
• Develop: www.develop.wrkbelt.com (apex develop.wrkbelt.com redirects to www)

Deployment Triggers:

• Automatic on push to main (staging) or develop branches
• Manual for production deployments

UI Application

The UI application serves the authenticated web application and handles all user interactions, dashboards, and business logic.

Domain Ownership:

• Production: app.wrkbelt.com and *.wrkbelt.com (wildcard for scheduler embeds)
• Staging: app.staging.wrkbelt.com and *.staging.wrkbelt.com
• Develop: app.develop.wrkbelt.com and *.develop.wrkbelt.com

Deployment Triggers:

• Automatic on push to main (staging) or develop branches
• Manual for production deployments

Frontend Deployment Flow

Both WWW and UI applications are deployed using GitHub Actions with SST and OpenNext:

Support Applications Deployment Flow

Dev-Docs and Storybook continue to be deployed using Netlify's continuous deployment:

Frontend Applications Build and Deployment

Both WWW and UI applications use NX for build orchestration and SST for deployment. This integration is configured in each app's project.json file:

{
  "targets": {
    "build": { /* NX Next.js build configuration */ },
    "setup-for-deploy": { /* Prepare for deployment */ },
    "open-next-build": { /* Run OpenNext build */ },
    "deploy": {
      "executor": "nx:run-commands",
      "dependsOn": ["open-next-build"],
      "options": {
        "cwd": "{projectRoot}",
        "command": "sst deploy --stage {args.stage}"
      },
      "configurations": {
        "production": { "args": ["--stage=production"] },
        "staging": { "args": ["--stage=staging"] },
        "develop": { "args": ["--stage=development"] }
      }
    }
  }
}

Deployment Commands:

• WWW: npx nx run www:deploy:{environment}
• UI: npx nx run ui:deploy:{environment}

Support Applications Selective Building

Netlify deployments for Dev-Docs and Storybook use an intelligent build process that only triggers when relevant files change. This is configured in the respective netlify.toml files:

The build decision script uses NX to determine if a project is affected by recent changes:

Frontend Applications Environment Variables

Both WWW and UI application environment variables are managed through .env files stored in S3:

S3 Structure:

s3://wrkbelt-env-files/
├── develop/
│   ├── www/.env
│   └── ui/.env
├── staging/
│   ├── www/.env
│   └── ui/.env
└── production/
    ├── www/.env
    └── ui/.env

Deployment Process:

1. GitHub Actions downloads the appropriate .env file from S3 based on environment and service
2. The .env file is copied to the app directory
3. SST deployment process includes these variables
4. Variables are securely passed to Lambda functions and available in the Next.js applications

Support Applications Environment Variables

Dev-Docs and Storybook manage environment variables through the Netlify dashboard:

1. Navigate to the Netlify site
2. Go to Site settings > Environment variables
3. Add or edit variables for each deploy context (production, deploy-preview, branch-deploy)

Frontend Applications Production Deployment

Deploying WWW or UI applications to production is handled through GitHub Actions workflows with manual approval:

For WWW Marketing Site:

1. Navigate to the GitHub repository Actions tab
2. Select "Prod WWW CI/CD Pipeline" workflow
3. Click "Run workflow"
4. Type "yes" in the confirmation field
5. Click "Run workflow" to begin deployment
6. Monitor the workflow logs for deployment status

For UI Application:

1. Navigate to the GitHub repository Actions tab
2. Select "Prod UI CI/CD Pipeline" workflow
3. Click "Run workflow"
4. Type "yes" in the confirmation field
5. Click "Run workflow" to begin deployment
6. Monitor the workflow logs for deployment status

Support Applications Production Deployment

Publishing Dev-Docs and Storybook to production requires manual approval in Netlify:

1. Log in to the Netlify dashboard
2. Select the site you want to deploy
3. Go to the "Deploys" tab
4. Find the deploy you want to promote (usually the latest successful staging deploy)
5. Click the "Publish deploy" button
6. Confirm the deployment

Environment Configuration

Development Environment

Development Status

The development environment is currently disabled and will be enabled after the V0.0.1 release.

When enabled, the development environment will:

• Automatically deploy from the develop branch
• Serve as an integration environment for new features
• Use development-specific environment variables

Staging Environment

The staging environment:

• Automatically deploys from the main branch
• Mirrors the production environment for testing
• Uses staging-specific environment variables
• Is accessible for internal testing and validation

Production Environment

The production environment:

• Requires manual deployment approval
• Serves the live application to end users
• Uses production-specific environment variables
• Has additional security and performance optimizations

Monitoring and Troubleshooting

Monitoring

Monitor deployments and application health through:

• GitHub Actions: Workflow run history and logs for API, WWW, and UI deployments
• AWS CloudWatch: API logs and metrics, WWW Lambda function logs, and UI Lambda function logs
• AWS CloudFormation: Stack creation and update logs for WWW and UI infrastructure
• SST Console: WWW and UI deployment and infrastructure status
• Netlify: Dev-Docs and Storybook deploy logs and analytics
• Slack Notifications: Automated deployment status updates for all pipelines

Common Issues and Solutions

API Deployment Issues

Issue	Possible Cause	Solution
Deployment fails	Missing or incorrect environment variables	Verify S3 .env files
Container crashes	Application error	Check CloudWatch logs
Timeout errors	Resource constraints	Adjust container resources

Frontend Deployment Issues

Issue	Possible Cause	Solution
WWW/UI build failure	Dependency or code issues	Check GitHub Actions logs
OpenNext build issues	Next.js compatibility problems	Verify Next.js version compatibility with OpenNext
SST deployment failure	AWS permission or config issues	Check CloudFormation and SST logs
Environment variable problems	Misconfigured variables	Verify S3 .env files
Domain verification failure	DNS propagation delay	Wait 5-10 minutes and retry
Support apps build failure	Dependency or code issues	Check Netlify build logs

Reference

Important Files

API Workflows:

• .github/workflows/cicd-api.yml - API CI/CD workflow
• .github/workflows/deploy-prod-api.yml - Production API deployment workflow

WWW Workflows:

• .github/workflows/cicd-www.yml - WWW CI/CD workflow
• .github/workflows/deploy-prod-www.yml - Production WWW deployment workflow

UI Workflows:

• .github/workflows/cicd-ui.yml - UI CI/CD workflow
• .github/workflows/deploy-prod-ui.yml - Production UI deployment workflow

Configuration Files:

• apps/www/sst.config.ts - SST configuration for WWW deployment
• apps/www/open-next.config.ts - OpenNext configuration for WWW
• apps/www/project.json - NX project configuration for WWW
• apps/ui/sst.config.ts - SST configuration for UI deployment
• apps/ui/open-next.config.ts - OpenNext configuration for UI
• apps/ui/project.json - NX project configuration for UI
• netlify.toml - Netlify configuration for support applications
• infra/src/bash/ui/should-build-netlify-app.sh - Build decision script for Netlify

Environment Decision Process

Deployment Checklist

Before deploying to production:

1. ✅ Verify all tests pass in staging environment
2. ✅ Perform manual QA testing on staging
3. ✅ Update documentation if needed
4. ✅ Plan rollback strategy in case of issues
5. ✅ Schedule deployment during appropriate time window
6. ✅ Notify team members of upcoming deployment
7. ✅ Monitor application metrics after deployment