Local Environment Setup for BFD Development

BFD Development Setup Guide

In order to develop and run BFD locally, there are a number of required pieces of software that will need to be installed. This guide intends to walk through the installation steps for that software in order to quickly get you up to speed on contributing to BFD.

Mac Instructions

Most developers who contribute to BFD are using Mac, so this setup guide will be focused on Mac-centric setup steps. If you need windows-specific help contributing to BFD, please contact the BFD team for support.

Homebrew

Homebrew is a command line tool for easily downloading and installing scripts, software, and artifacts.

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

Homebrew allows very easy installation of things with simple commands like brew install X where X is the name of the software/package/installation you want to download. Homebrew will be used for many of the installation instructions in this guide, since it simplifies the installation process.

Java

BFD is currently using Java 17. There are many ways to get the SDK for java installed on your machine. BFD currently recommends the amazon corretto SDK, to align with our deployed SDK versions. https://docs.aws.amazon.com/corretto/latest/corretto-17-ug/macos-install.html

Another option is to use openJdk with brew: brew install openjdk@17

Either SDK should be functionally equivalent, but corretto may have minor bugfixes and performance improvements over openJdk.

After installing Java, set your JAVA_HOME environment variable in the terminal:

export JAVA_HOME="$(/usr/libexec/java_home)"

Maven

Maven is used to manage building the application and artifacts/dependencies. Installing it is easy:

brew install maven

Once installed you can test it with mvn -version which should look something like this:

AWS

Amazon Web Services (AWS) are heavily used in the project. The command line tool (CLI) lets you communicate with AWS with easy terminal commands and is occasionally useful for transferring files to and from your local machine during development.

Follow the instructions here to install the CLI: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

You should just need to download/run the PKG, but you can also install via the command line if you’d like.

Initially, you won’t have an AWS account to connect to and use AWS. Get an account by following the instructions here under “VPN and AWS”: https://confluence.cms.gov/pages/viewpage.action?pageId=302580951

Once you have an AWS account, you can log into AWS console site, which is used to manage the databases, load files, and other aspects of the deployed application environments.

You’ll want to properly setup your access key and 2FA in the AWS console as well:

1. Log into AWS (and proceed to security credentials) via https://console.aws.amazon.com/iam/home?#/security_credentials
2. Set up your 2 factor authentication by following the steps here: Enabling a virtual multi-factor authentication (MFA) device (console) - AWS Identity and Access Management

• It is recommended to use Google Authenticator for this.
• Once set up, your device should appear on the security credentials page at the bottom like this, with a unique device ID for your device: (TODO: add image)

1. Click “Create Access Key” (TODO: add image)
2. Once clicked, it will create an access key and allow you to get the secret value once. Leave this window open (dont complete the setup of the key yet)
3. Generate an initial dummy aws configuration file by doing aws configure on the command line and filling in any value when prompted (we'll replace them shortly)
4. Open the file in your text editor of choice. The file should have been created at ~/.aws/config

(Work In Progress)