Developer Onboarding

Developer Onboarding

Welcome to the Firefly development team! This guide will help you set up your development environment and get your first contribution ready.

Prerequisites

Before you begin, ensure you have:

Development Environment Setup

1. Install Package Managers

Install Homebrew (macOS/Linux package manager):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install nvm (Node Version Manager):

brew install nvm

2. Install Node.js

Install Node.js 20 (version 20.15 or newer):

nvm install 20
nvm use 20

3. Install Yarn

Install Yarn package manager:

npm install --global yarn

4. Install AWS Tools

Install AWS CLI v2 (version 2.13.16 or newer):

# macOS
brew install awscli

# Verify installation
aws --version

5. Set Up Amazon Developer Account (ADA) CLI

  1. Authenticate with Midway:

    mwinit

  2. Install Builder Toolbox (if not already installed):

  3. Install ADA CLI:

    toolbox install ada

6. Set Up Firefly Development Alias

Instead of manually running multiple setup commands each time, create a convenient alias that handles all Firefly development setup.

First, run this command to attach an auth header to all requests to get packages from CodeArtifact. This will prevent attempts without using authentication.

echo always-auth=true >> ~/.npmrc

Add this alias to your shell profile (.bashrc, .zshrc, or .bash_profile):

firefly() {
    echo "Setting up AWS credentials..."
    ada credentials update --provider conduit \
       --role firefly-dev-ada-role \
       --once \
       --account 929488686603 \
       --profile firefly-dev
 
    echo "Setting environment variables..."
    export AWS_PROFILE=firefly-dev
    export STAGE=dev
    export NODE_OPTIONS=--max_old_space_size=8172
 
    echo "Logging into CodeArtifact..."
    aws codeartifact login --tool npm \
        --repository music-sonic \
        --domain amazon \
        --domain-owner 149122183214 \
        --region us-west-2
}

What this alias does:

  1. AWS Credentials: Updates your AWS credentials using the Firefly development role

  2. Environment Setup: Sets required environment variables for development

    • AWS_PROFILE=firefly-dev: Uses the correct AWS profile for Firefly

    • STAGE=dev: Sets development stage

    • NODE_OPTIONS=--max_old_space_size=8172: Increases Node.js memory limit for large builds

  3. CodeArtifact Login: Authenticates npm with Amazon’s internal package repository

To use the alias:

# Reload your shell configuration
source ~/.zshrc  # or ~/.bashrc

# Run the setup (do this daily or when authentication expires)
firefly

When to run firefly:

  • At the start of each development session

  • When you get authentication errors

  • When CodeArtifact login expires (typically daily)

  • Before building or installing dependencies

7. Install Development Tools

Install Commitizen for standardized commit messages:

npm install -g commitizen
npm install -g cz-conventional-changelog

Configure Commitizen globally:

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

Important: Commitizen is required for all Firefly contributors. Firefly uses semantic-release to automatically trigger deployments and version releases based on your commit messages, so incorrect formatting will break the pipeline. Always use git cz instead of git commit.

8. Verify Access Permissions

Ensure you have access to the Firefly Bindle:

  1. Sign in to the bindle link above

  2. Select See all permissions

  3. Verify your name or team is listed

This bindle provides access to required IAM roles for development.

Get the Code

1. Create Development Directory

mkdir -p ~/Code/Firefly
cd ~/Code/Firefly

2. Clone Repositories

Authenticate with Midway first:

mwinit

Note: If the standard mwinit command doesn’t detect your SSH key, try using mwinit -k.

Clone the main repositories:

# Clone MetalFly Core (amu_webapi)
git clone git@ssh.gitlab.aws.dev:amazonmusic/musicfirefly/amu_webapi

# Clone MetalFly API
git clone git@ssh.gitlab.aws.dev:amazonmusic/musicfirefly/services/metalfly_api

3. Install Dependencies

For each repository:

cd amu_webapi
yarn install
cd cdk
yarn install

cd ../../metalfly_api
yarn install
cd cdk
yarn install

Verify Your Setup

1. Test the Firefly Alias

firefly

You should see output showing:

  • AWS credentials being updated

  • Environment variables being set

  • CodeArtifact login success

2. Test AWS Access

aws sts get-caller-identity

You should see your AWS account information with the Firefly development role.

3. Test CodeArtifact Access

npm config get registry

Should show a CodeArtifact registry URL (not the default npm registry).

4. Test Repository Access

cd ~/Code/Firefly/amu_webapi
yarn build

If this completes successfully, your basic setup is working!

5. Test Commitizen

# In any git repository
git cz --help

Should show Commitizen help information.

Tip: If after running git cz you get the error git: 'cz' is not a git command or cz is not command, the solution is to get the yarn global bin path by running yarn global bin and then add that path in path variable in the ~/.zshrc file.

  • One method is to use the following command to add a directory to the PATH: export PATH="/path/to/your/directory:$PATH"

  • Verify that the directory has been added: echo $path

Next Steps

Now that your environment is set up, choose your development approach:

For Local Development

  • Recommended: Follow the Local Development Guide

  • Benefits: Fast iteration, hot reloading, no AWS deployments needed

For Cloud Development

  • Alternative: Follow the Deployed Dev Stack Guide

  • Benefits: Production-like environment, easier debugging of AWS-specific issues, supports more services

Getting Help

For troubleshooting common setup issues, see the Troubleshooting Guide.

Support Channels

What’s Next?

  1. Make your first query: Try the Quick Start Guide

  2. Set up development: Choose Local Development or Deployed Dev Stack

  3. Learn the codebase: Review the Development Guidelines

  4. Make your first contribution: Read Contributing Guidelines