Local Development

This page will guide you through some basic points for getting started developing against the DCE codebase.

Note: unless otherwise noted, all commands shown here should be executed from the DCE base directory

Configuring your development environment

You may find development easiest on a Mac OS or Linux-based machine. Development should be possible on Windows 10 with the Windows Subsystem for Linux installed, but at the time of this writing has not been verified.

You will need the following:

  1. Go (version 1.13.x)
  2. Terraform (version v0.12.x)
  3. GNU make (version 3.x)
  4. GNU bash, which is used for shell scripts
  5. An AWS account for deploying resources
  6. The AWS CLI Note: if you install version 2, see “Configuring AWS CLI 2”
  7. An AWS IAM user with command line access.
  8. Git (version 2.x)

**Important: deploying DCE to your AWS account can incur cost.**

Configuring AWS CLI 2

The AWS CLI version 2 includes a breaking change that creates problems with the automation scripts. See https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html for more information.

For DCE, the recommeonded solution to this problem is to add the following line in your ~/aws/config file:

[default]
cli_pager=

Getting the code locally

To get the code locally fork this repo (https://github.com/Optum/dce) and then clone the repository:

git clone https://github.com/${mygithubid}/dce.git dce # replace with your fork's HTTPS URL
cd dce
make setup

The last command, make setup, will run the scripts/install_ci.sh script which will install the necessary tools for building and testing the project.

Code Structure

The DCE codebase is comprised of Go application code, along with Terraform infrastructure configuration.

The Go code is primarily located within:

  • /cmd: entrypoint for applications targeting AWS Lambdas and CodeBuild
  • /pkg: common services used by entrypoint code.

Each subdirectory within the /cmd/lambda directory targets an individual Lambda function of the same name.

Building application code

To compile the Go application code, run:

make build

This generates a /bin/build_artifacts.zip file, which includes Go binaries for each entrypoint application.

Unit Tests

Unit tests are located within the /cmd and /pkg directories, adjacent to their corresponding Go code. So, for example, the code in /pkg/api/user_test.go includes tests against /pkg/api/user.go.

Execute unit tests by running:

make test

Code Linting

When you run make test, the lint target is executed automatically. You can, however, run the linting by itself by using the command:

make lint

During make lint, the scripts/lint.sh script executes golangci-lint. The configuration file is .golangci.yml. Enabled linters and rule exceptions can be found in this file.

The make lint target also executes tflint to lint the terraform code found in modules.

Functional Tests

Functional tests are located in tests and are used to test the integration between a number of services or verify that end-to-end behavior is working properly. For example, we rely heavily on functional tests for DynamoDB interactions, to verify that we are using the DynamoDB SDKs correctly.

Before running functional tests, DCE must be deployed to a test AWS account. Functional tests truncate the database tables, so do not run them against production environments.

To deploy DCE for testing, first authenticate against an AWS test account, then run:

# Deploy AWS infrastructure using Terraform
cd modules
terraform init
terraform apply

# Deploy application code to AWS
cd ..
make deploy

See Deploying DCE With Terraform for more details.

To run functional tests:

make test_functional

Functional tests load the details of the DCE deployment from Terraform module outputs, so there is no need for additional configuration to run functional tests.

Before committing code

The make test target is used by continuous integration build. A failure of the target will cause the build to fail, so before committing code or creating a pull request you should run the following commands:

make build
make test

Building the documentation

The documentation is located in docs and is based on the Sphinx project and hosted on http://readthedocs.io.

If you are making changes to documenation and would like to verify the build of the documentation, you will need to make sure Python 3 is installed. It is highly recommended that you use virtualenv and configure your workspace with the commands shown here:

virtualenv -p python3 ENV
source ENV/bin/activate
pip install -r docs/requirements.txt

With the Python requirements installed and the virtualenv sourced, use the following command from the base project directory:

make documentation

To serve the documentation locally, run the following command:

make serve_docs

By default, the documenation will be served at http://127.0.0.1:8000.