Setup Checklist - MacPro Mako

🏠 Local Development Setup

Prerequisites Installation

Node.js (v18 or higher)

node --version
# Should show v18.x.x or higher

Bun (v1.1.20 or higher)

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bun --version
# Should show 1.1.20 or higher

Git
```
git --version
```

AWS CLI (optional for local dev)

aws --version
aws configure  # Set up credentials if needed

Project Setup

Clone repository

git clone <repository-url>
cd macpro-mako

Install dependencies
```
bun install
```

Verify installation

bun run test-tsc  # Should pass without errors

Environment Configuration

Create environment file

cp .env.example .env  # If example exists
# Or create .env manually

Set local environment variables

# Add to .env file
PROJECT="your-project-name"
STAGE="local"
REGION_A="us-east-1"

Development Server Setup

Start frontend development server

bun run bun:dev
# Should start on http://localhost:5000

Verify frontend loads
- Open browser to http://localhost:5000
- Check for any console errors
Run tests to verify setup
```
bun run test
# Should pass all tests
```

Optional Local Services

Docker (if needed for local services)
```
docker --version
```

Local database (if needed)

# Set up local OpenSearch or other database

☁️ AWS Deployment Setup

AWS Account Setup

AWS Account with appropriate permissions
- Administrator access or equivalent
- Billing access

AWS CLI configuration

aws configure
# Enter your AWS Access Key ID
# Enter your AWS Secret Access Key
# Enter your default region (e.g., us-east-1)

Verify AWS credentials

aws sts get-caller-identity
# Should show your account ID and user info

CDK Setup

Install AWS CDK globally
```
npm install -g aws-cdk
cdk --version
```

Bootstrap CDK (first time only)

cdk bootstrap
# This sets up S3 bucket and IAM roles for CDK

Secrets Configuration

Create project-default secret

aws secretsmanager create-secret \
  --name "your-project-default" \
  --secret-string '{
    "brokerString": "your-kafka-broker-string",
    "dbInfoSecretName": "your-db-secret-name",
    "devPasswordArn": "arn:aws:secretsmanager:region:account:secret:name",
    "domainCertificateArn": "arn:aws:acm:region:account:certificate/cert-id",
    "domainName": "your-domain.com",
    "emailAddressLookupSecretName": "email-lookup-secret",
    "notificationSecretName": "notification-secret",
    "notificationSecretArn": "arn:aws:secretsmanager:region:account:secret:name",
    "googleAnalyticsDisable": false,
    "googleAnalyticsGTag": "G-XXXXXXXXXX",
    "iamPath": "/your-project/",
    "iamPermissionsBoundary": "arn:aws:iam::account:policy/boundary",
    "idmAuthzApiEndpoint": "https://your-idm-endpoint",
    "idmAuthzApiKeyArn": "arn:aws:secretsmanager:region:account:secret:name",
    "idmClientId": "your-idm-client-id",
    "idmClientIssuer": "https://your-idm-issuer",
    "idmClientSecretArn": "arn:aws:secretsmanager:region:account:secret:name",
    "idmEnable": false,
    "idmHomeUrl": "https://your-idm-home-url",
    "legacyS3AccessRoleArn": "arn:aws:iam::account:role/legacy-s3-access",
    "useSharedOpenSearch": false,
    "vpcName": "your-vpc-name"
  }'

Create stage-specific secret (optional)

aws secretsmanager create-secret \
  --name "your-project-local" \
  --secret-string '{
    "stage": "local",
    "isDev": true
  }'

Environment Variables

Set required environment variables

export PROJECT="your-project-name"
export REGION_A="us-east-1"
export CDK_DEFAULT_ACCOUNT="your-aws-account-id"
export CDK_DEFAULT_REGION="us-east-1"
export STAGE="local"  # or dev, val, production

Infrastructure Deployment

Deploy to local stage

cdk deploy -c stage=local
# This will create all AWS resources

Verify deployment

# Check CloudFormation stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE

# Check deployed resources
cdk list

Get deployment outputs

# Get deployment configuration
aws ssm get-parameter --name "/your-project/local/deployment-output"

Domain & SSL Setup (Production)

Domain name registered
SSL certificate in AWS Certificate Manager
DNS configuration pointing to CloudFront
Update domain configuration in secrets

🔧 Development Workflow Setup

Git Configuration

Configure Git user

git config user.name "Your Name"
git config user.email "[email protected]"

Set up Git hooks (if any)

# Check for pre-commit hooks
ls -la .git/hooks/

IDE Setup

VS Code (recommended)
- Install TypeScript extension
- Install ESLint extension
- Install Prettier extension
- Install AWS Toolkit extension

Configure workspace settings

// .vscode/settings.json
{
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Testing Setup

Verify test environment

bun run test
# Should run all unit tests successfully

Verify E2E tests

bun run e2e
# Should run all end-to-end tests

Check test coverage

bun run test:coverage
# Should generate coverage report

🚀 Production Deployment Checklist

Pre-Deployment

Code review completed
All tests passing
Security scan completed
Performance testing completed
Backup of current production data

Deployment Steps

Deploy to validation environment
```
cdk deploy -c stage=val
```
Run smoke tests on validation
Deploy to production
```
cdk deploy -c stage=production
```
Verify production deployment
- Check application health
- Verify all features work
- Monitor error rates
- Check performance metrics

Post-Deployment

Monitor application for 24-48 hours
Check CloudWatch logs for errors
Verify user access and functionality
Update documentation if needed

🔍 Verification Commands

Local Development

# Check all systems
bun run test-tsc    # TypeScript compilation
bun run test        # Unit tests
bun run e2e         # End-to-end tests
bun run lint        # Code linting
bun run format:check # Code formatting

AWS Deployment

# Check AWS resources
cdk list            # List all stacks
cdk diff            # Show pending changes
aws cloudformation describe-stacks --stack-name your-project-local

Application Health

# Check frontend
curl -I http://localhost:5000

# Check API (if deployed)
curl -I https://your-api-gateway-url/health

# Check database connectivity
# (Use AWS console or CLI to verify OpenSearch)

🚨 Troubleshooting Checklist

Common Issues

Bun not found: Reinstall with curl -fsSL https://bun.sh/install | bash
CDK errors: Run cdk bootstrap first
TypeScript errors: Clear cache with rm -rf node_modules/.cache
AWS credentials: Verify with aws sts get-caller-identity
Permission errors: Check IAM roles and policies
Network issues: Check VPC and security group configurations

Getting Help

Check project documentation
Review AWS CDK documentation
Check TypeScript/React documentation
Look at existing code examples
Check GitHub issues for similar problems

Note: This checklist should be completed in order. Each section builds upon the previous one. If you encounter issues at any step, resolve them before proceeding to the next step.