| Branch | CircleCI Status | | :--- | :--- | | staging | | | master | |

Table of Content

• Getting Started
  • Install dev
  • Symlink podman
  • Environment variables
  • Production database migrations
• Local development
  • Run database migrations
  • Make API calls
  • Invoke a function
  • Add a route
  • Visualize Swagger Documentation
• Test in staging
• Publish a sub-package
  • Revert git tags

Getting Started

Install SlimDev

Follow the instructions here to install slim dev if you don't yet have it.

This instructions assume you are working on this repo from a Flexport-issued Macbook.

Symlink Podman

NOTE: Only applies to Podman users, in other words anyone working from a Shopify-issued Macbook.

If you use Podman, you should symlink Podman commands to Docker commands:

ln -s /opt/homebrew/bin/podman /opt/homebrew/bin/docker

and

ln -s /opt/homebrew/bin/podman-compose /opt/homebrew/bin/docker-compose

NOTE: your Podman installation may be in a different spot. Use which podman to find out.

The reason for symlinking is that several npm commands use docker run and without this symlink, these commands may not run correctly.

Environment Variables

env variables are managed using config.env.json files and are populated through SSM.

Please make sure to update these files when introducing a new environment variable as well as in SSM, try to avoid directly referencing SSM in the serverless.yml

Fetch Environment Variables for Local Development

To run npx sls offline start locally, fetch all required environment variables from AWS SSM:

Staging:

./dev/fetch-ssm-env.sh --stage=staging --aws-profile=staging

Production:

./dev/fetch-ssm-env.sh --stage=prod --aws-profile=prod

This generates a .env.{stage} file (e.g., .env.staging) with all variables needed for local development.

Then start the server:

AWS_PROFILE=staging npx sls offline start --stage staging

Note: Requires jq to be installed (brew install jq). See dev/FETCH_SSM_ENV_README.md for details.

Override Variables (Optional)

To override existing variables create a .env and put all desired environment variables in that file.

Note: Environment variables for testing are set through the setEnvVars.js please make sure to update with all neccessary credentials to ensure tests will pass.

Production database migrations

Database migrations for prod are run via the terminal. You can find the database credentials in SSM.

Local Development

Run Database Migrations

Running dev up will (among other steps) run all the migrations to properly configure your database.

If you don't want to run all the steps in dev up and only care about migrations you can follow these instructions:

1. make sure the MySQL server is up, if not you can start it by running:

docker-compose up

2. Once the server is up, execute the following command to run migrations:

DATABASE_URL=mysql://deliverr:deliverr@localhost:3306/freight npx knex migrate:latest --env development

NOTE: You can check docker-compose.yml to confirm the correctness of local port number, DB name, user and password used in the command.

NOTE To populate your local Zip, FtlRate, LtlRate, and RateRange tables with real data, run dev seed-rates. To do this, you'll need to have the SNOWFLAKE_URL environment variable popualted, the value of which can be found in the AWS parameter store.

Make API Calls

Running dev server will start the server and have it ready to receive API calls.

Once the server is running you can access the API at http://localhost:3000/vX/<your-pick>.

Invoke A Function

npx sls invoke local -f <function-name>

Add A Route

once you add a new route, run the following command to create the auto-generated files and then you'll be able to call the new endpoint

npm run generate-sources

Visualize Swagger Documentation

1. Start Swagger server

   npm run swagger-ui

2. The Swagger API documentation is available at http://localhost:65420

Test in staging

NOTE: This is required if you're modifying the Serverless config.

To test your changes in Staging you will need to:

1. Join the #dev-freight-service-repo-claim-release slack channel and check if staging has been already claimed by someone else.

2. If it's claimed by someone else contact that person or wait in line until the person is done.

3. If free, write a message to that channel saying that you are claiming Staging.

4. Before testing your changes in Staging you should run migrations regardless of whether you added migrations or not.

   You can first check if there are any pending migrations:

   DATABASE_URL=[staging_database_url] knex migrate:list

   In case there are pending migrations, you can run them all with the command below:

   DATABASE_URL=[staging_database_url] knex migrate:latest

5. After that, run the following commands in order to push your changes to staging remote branch:

   git checkout <your_feature_branch> # in case you are not already in your feature branch
   git branch -D staging # this will delete your local version of the staging branch
   git checkout -b staging # and here you will recreate your local staging branch based off your feature branch
   git push origin +staging # then you override staging on remote with your local changes

   You can check the deployment status in Staging in CircleCI

6. Once you're done testing your changes:

   If you added migrations as part of the change you were testing, roll them back.

   DATABASE_URL=[staging_database_url] knex migrate:rollback

   Also don't forget to announce that you are releasing Staging by writing a message to the slack channel.

Publish A Sub-package

1. Bump the version in ./[sub-package name]/package.json -- the package.json file from the sub-package directory.

2. Start a shell -- in the sub-package directory

   npm install

3. Commit your changes to git for package.json & package-lock.json (making sure the changes are pushed to remote)

4. Push your changes upstream. CircleCi will automatically publish this new version in our npm registry and Git (as a tag) as part of its build.

Manually publishing a new client version (NOT NEEDED IN MOST CASES)

From the same shell as above

npm run build-and-publish

Revert git tags

Note: This only applies if running npm run build-and-publish fails

1. Find tag that you created

   git tag

2. Delete tag on local

   git tag -d [tagname]

3. Delete tag on remote

   git push --delete origin [tagname]