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:
- Go (version 1.13.x)
- Terraform (version v0.12.x)
- GNU make (version 3.x)
- GNU bash, which is used for shell scripts
- An AWS account for deploying resources
- The AWS CLI Note: if you install version 2, see “Configuring AWS CLI 2”
- An AWS IAM user with command line access.
- 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
.