Deployed Developer Stack Guide

Deployed Developer Stack Guide

Prerequisites

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

Additional Requirements:

Begin your deployment

This will deploy to AWS firefly-music-dev. Note: You need to perform these steps for both the metalfly_api and amu_webapi packages.

  1. Install your requirements:

    yarn install
cd cdk
yarn install

    Note: It is important to consistently use yarn and not npm for intalling dependencies unless otherwise noted. We deploy with yarn so any installations done with npm are not guaranteed to be included in the deployment.

  2. Compile your code:

    yarn build

  3. To deploy:

yarn dev-deploy:iad

Note: If you get errors, you may need to re-run the firefly script from the Developer Onboarding document.

Available Deployment Commands

  • yarn dev-deploy:iad for us-east-1

  • yarn dev-deploy:dub for eu-west-1

  • yarn dev-deploy:pdx for us-west-2

Or

  • yarn dev-deploy:all for all three regions

Post-Deployment

After deployment, you’ll see 3 CloudFormation stacks in the dev account:

  • MetalFly-API-<username>

  • MetalFly-Core-<username>

  • MusicFirefly-<username>

MetalFly API generates Global Accelerator endpoints in this format:

https://<SDE_ALIAS>.<AWS_REGION>.metal.beta.gql.music.amazon.dev

Example: https://ryanyhu.us-east-1.metal.beta.gql.music.amazon.dev/

Insomnia Setup

Please see the Insomnia setup guide to simplify LoginWithAmazon integration and test directly against your new API endpoint.

Running the tests

There are two types of test suites available: unit and integration tests.

  • Run the unit tests:

yarn test

  • Run the integration tests against your own deployed endpoints:

yarn testIntegration

You can also run the integration tests against your own endpoints as deployed in the previous section. In order to do so you need to create the file endpoint.env in the root directory with this content:

NA_ENDPOINT=https://REPLACE-WITH-YOUR-NA-ENDPOINT.execute-api.us-east-1.amazonaws.com/dev/
EU_ENDPOINT=https://REPLACE-WITH-YOUR-EU-ENDPOINT.execute-api.eu-west-1.amazonaws.com/dev/
FE_ENDPOINT=https://REPLACE-WITH-YOUR-FE-ENDPOINT.execute-api.us-west-2.amazonaws.com/dev/

Populate the file with your own endpoint values as obtained when deploying your stack to NA, EU and FE geographic regions. After you create this file, the integration tests will use your endpoints.

Note: If you are testing a new client integration, have the Devex API Team on-call add your Lambda role to the AAA page for MusicFireFlyService. This allows your developer stack to retrieve the token from the client. If this is not done, the token will return null.

Test client service package changes with amu_webapi

Since the amu_webapi package is a separate project from client service packages, local changes to the client need to be connected to amu_webapi.

  • yarn pack is recommended.

  • yarn pack is required if you want to test against your devstack using Insomnia, so your changes get deployed.

Yarn pack instructions

Yarn Pack will build the client package and contain it in a compressed file which can be referenced by another project. This will allow amu_webapi dev deployment to include the local client changes.

Step 1: Pack

Make sure to install and build before you pack:

yarn install --force && yarn build

Navigate to the root of your local client package and run:

yarn pack

If it ran successfully, you should be able to see a new .tgz file in the project folder. You should be able to see the newly created file by running git status in the client package.

your-client-package-v1.0.0.tgz

Run this step before each dev deployment.

Note: If the deployment is not reflecting the changes, you may need to bump the version number of the client package. Make this change in the package.json in the client package under version.

Step 2: Point amu_webapi to the packed file

Edit package.json of the amu_webapi project. Add this line, replacing the version.

  "dependencies": {
    ...
    your-client-package: "file:RELATIVE_PATH_TO_CLIENT_PACKAGE/your-client-package-v1.0.0.tgz",
    ...
  }

The packed file is now linked and you should be able to deploy to your local dev. You only have to perform this step once.

Note: When you are ready to commit your changes, return this dependency to the original state.

  "dependencies": {
    ...
    your-client-package: "^1.0.0",
    ...
  }

Note:

  • If you encounter an error when running yarn install, you may have a space after file: that needs to be removed.

  • You also might need to run yarn cache clean, or increment the dependency’s version number, to get the yarn cache to recognize newly-built changes in the .tgz file.

Making changes on FireFly

Flow overview:

  • Create a local branch with your changes

git checkout -b my-new-branch

Note: Make sure you are not tracking origin/main with this new branch.

  • Make your changes and stage them

git add .

  • Add a commit using commitzen and follow the prompts

git cz

  • Publish your changes to your remote branch. Gitlab will provide you with a link to create a merge request

git push origin my-new-branch

For more details on how to Contribute to the firefly codebase and our process, see the Firefly contribution guidelines.

To learn more about Gitlab merge requests, see Creating merge requests.

FAQ

After I deploy FireFly against a dev stack, where should I check the logs?

You will find a log group for your username in your firefly-dev account.

Do I need to deploy MetalFly API for every amu_webapi change?

For submitting MRs to amu_webapi, you need to deploy your MetalFly API cluster to each region ONCE, otherwise MR will fail with deploy:Core:dev [region] error. See the Troubleshooting Guide for details.

If your MetalFly API cluster is already deployed, you do not need to deploy it again.