Skip to content

Developer Setup

Jump to bottom
Benjamin Paige edited this page Sep 16, 2025 · 3 revisions

Developer Setup

Appian Connector Development Environment Setup

Page Navigation: ← Home | Workspace Setup | AWS Authentication | Alert Subscriptions | Development Workflows | Next: Architecture →

Workspace Setup

Required Development Tools

Tool Version Required Purpose
MacOS 10.15+ Yes Operating system
Rosetta 2 2 Yes (Apple Silicon) Intel compatibility
XCode Command Line Tools Latest Yes Development utilities
NodeJS 20.x Yes Runtime environment
Node Version Manager (NVM) Latest Yes Node version management
Yarn 1.22+ Yes Package management
Direnv Latest Yes Environment variable management
AWS CLI 2.x Yes AWS command line
AWS SSM Plugin Latest Yes ECS session access
jq Latest Yes JSON processing

Apple Silicon Setup (M1/M2/M3 Macs)

# Install Rosetta 2 for Intel compatibility
/usr/sbin/softwareupdate --install-rosetta --agree-to-license

Automated Setup

# Download and run setup script
curl -O https://raw.githubusercontent.com/Enterprise-CMCS/macpro-appian-connector/master/docs/assets/setup.sh
chmod +x setup.sh
./setup.sh

# Close all terminals and reopen for PATH updates

Repository Setup

# Clone repository with SSH (recommended)
git clone git@github.com:Enterprise-CMCS/macpro-appian-connector.git
cd macpro-appian-connector

# Configure environment
nvm use
yarn install
direnv allow  # Load environment variables

AWS Authentication

Kion (CloudTamer) Access

Console Access

  1. Connect to VPN: https://cloudvpn.cms.gov
  2. Access Kion: https://cloudtamer.cms.gov/login
  3. Login: Use CMS EUA credentials
  4. Select Account: Choose appropriate AWS account
  5. Choose Role: Select Cloud Access Roles
  6. Web Access: Opens AWS Console (VPN can be disconnected after)

CLI Credentials (4-hour validity)

  1. Follow steps 1-4 above
  2. Select: 'Short-term Access Keys'
  3. Copy: Option 1 environment variables
  4. Paste: Into terminal for programmatic access
# Example credentials (expires in 4 hours)
export AWS_ACCESS_KEY_ID="ASIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."

Alert Subscriptions

SNS Alert Setup

Subscribe to Notifications

  1. Access AWS Console via Kion
  2. Navigate to SNS in us-east-1 region
  3. Find Topic: Alerts-appian-connector-alerts-{stage}
  4. Add Subscription:
    • Protocol: Email
    • Endpoint: Your email address
  5. Confirm: Click confirmation link in email

Environment Recommendations

  • ✅ Subscribe to: master, val, production environments
  • ❌ Avoid: Feature branch environments (too noisy)

Development Workflows

GitOps Deployment

Automatic Deployment

# Create and push feature branch (triggers automatic deployment)
git checkout master
git pull
git checkout -b feature/package-fix
git push --set-upstream origin feature/package-fix

# Monitor deployment at:
# https://github.com/Enterprise-CMCS/macpro-appian-connector/actions

Manual Deployment

# Deploy entire application
./run deploy --stage {stage-name}

# Deploy specific service
./run deploy --service connector --stage {stage-name}

ECS Container Access

Connect to Connector Container

# Get connection command
./run connect --stage {stage} --service connector

# Copy and run the outputted ECS exec command
# Inside container - access Kafka Connect REST API
curl http://localhost:8083/connectors | jq .
curl http://localhost:8083/connectors/source.jdbc.appian-connector-dbo-1/status

Port Forwarding for Connector UI

# Get port forwarding command  
./run connect --stage {stage} --service connector

# Look for 'ecs-exec-pf' command in output
# Run it to enable localhost:8083 access

Development Metrics

DORA Metrics Dashboard

The Appian Connector project publishes Development Operations Research and Assessment (DORA) metrics for team efficiency tracking.

Access Development Metrics

  • DORA Dashboard: https://enterprise-cmcs.github.io/macpro-appian-connector/metrics/dora
  • AWS Resources: https://enterprise-cmcs.github.io/macpro-appian-connector/metrics/aws

Key Metrics Tracked

  • Deployment Frequency: Automated branch deployments
  • Lead Time for Changes: Commit to production time
  • Change Failure Rate: Deployment success rate
  • Time to Recovery: Incident resolution time

Troubleshooting Setup Issues

Common Setup Problems

AWS CLI Configuration Issues

# Test AWS connectivity
aws sts get-caller-identity

# If fails, reconfigure AWS CLI
aws configure

Node Version Issues

# Use project Node version
nvm use

# If Node version not found
nvm install $(cat .nvmrc)
nvm use

Direnv Issues

# Allow environment variables
direnv allow

# If direnv not working, check installation
direnv version

Related Documentation

Next Steps After Setup

Operational Guides

External Resources

Next: After completing setup, proceed to Architecture to understand the system design or Configuration for Oracle connectivity setup.

Clone this wiki locally