Local Development Guide

Local Development Guide

Last Updated: 07/29/2025

This guide provides instructions on setting up and using a local development environment for the Firefly service.

Overview

The local development environment allows you to:

  • Develop

  • Test

  • Iterate

on the Firefly service without needing to continuously deploy to AWS.

Source of Truth

For the most current local development instructions and updates, refer to the Main Sage Post on FireFly Local Development. This post serves as the authoritative source and will likely contain updates throughout the lifecycle evolution of the local development process.

Important Update: Migration to MetalFly

🚨 As of 6/6/2025, the method for local development has changed as FireFly is shifting all local development to MetalFly.

Key Changes:

  • Commands used for local development in FireFly (e.g., yarn startLocalDevEnvironment, yarn deployLocal) no longer work

  • You must deploy your MetalFly API and MetalFly Core stacks first to do local development

  • Local development now requires both MetalFly API and MetalFly Core repositories

  • Your local host is ready when you see "host": "localhost:3000" in the response payload

Key features of the new setup:

  • Docker-based development using Docker Compose or Podman

  • Hot reloading capability to view code changes in real-time

  • Full local development without requiring continuous deployments when both MetalFly API and Core are running locally

Prerequisites

You should have the following from installing the prerequisites in the Developer Onboarding guide:

Additional Requirements:

Important VPN Configuration:

  • Connect your VPN to a specific region instead of Automatic Selection.

    • Otherwise, your nearest cloudauth server might be changing and you might have to redo the local-setup.

    • For example, CA users can connect to Herndon, VA, US (us-east-1) or Seattle, WA, US (us-west-2).

Setup Guide

1. MetalFly API Setup

Clone and set up the MetalFly API repository:

git clone https://gitlab.aws.dev/amazonmusic/musicfirefly/services/metalfly_api
cd metalfly_api
yarn install
cd cdk
yarn install

2. Running MetalFly API Locally

You can run MetalFly API locally using either of these methods:

Option A: Using Yarn Script

yarn start:docker

Option B: Using Docker Compose Directly

docker compose up --build

For Podman Users:

podman compose up --build

To terminate the process, use CTRL + C in the terminal.

3. MetalFly Core Integration

To enable full local development with MetalFly Core:

  1. Ensure Cisco VPN connection to your target region

  2. Clone MetalFly Core repository:

    git clone https://gitlab.aws.dev/amazonmusic/musicfirefly/amu_webapi
cd amu_webapi
yarn install

  3. Start MetalFly Core locally:

    docker compose up
# or for podman users
podman compose up

Using the Local Environment

Once both services are running:

  • MetalFly API endpoint: http://localhost:3000/

  • Supported endpoints:

    • POST http://localhost:3000/

    • GET http://localhost:3000/ping

    • GET http://localhost:3000/info

You can use the Firefly Console for testing, or use Insomnia with the local endpoint instead of https://gql.music.amazon.dev.

See the Insomnia setup guide for more detail.

Troubleshooting

For comprehensive troubleshooting of local development issues, see the Troubleshooting Guide.

Diagnostic Tools

The MetalFly API repository includes a diagnostic script to help troubleshoot local development issues:

yarn doctor

FAQ

Should I redeploy each time I make a change?
No. For full local development (both MetalFly API and Core), deployments are not required for every change. However, it’s good practice to deploy your Metal stack at least once to create necessary AWS resources.

Will my changes be picked up automatically?
Yes, as long as your session hasn’t expired, changes will be picked up automatically without restarting the containers.

Why do I need both MetalFly API and Core for full local development?
This setup allows you to test changes without deployments. MetalFly API handles the GraphQL endpoint while MetalFly Core processes the business logic.

What happened to the old local development commands?
The previous commands (yarn startLocalDevEnvironment, yarn deployLocal) no longer work due to the migration to MetalFly. All local development now uses the Docker-based MetalFly setup.

Additional Resources

Support

If you encounter issues not covered in this guide, please reach out to the team or check the related Sage posts linked above.