New Domain Setup

To set up a new domain folder and deployment configuration for a Partner Team, this page enumerates the tasks, which are organized into the following stages:

1. Gradle domain subproject for all domain code
2. Docker configurations to containerize applications
3. Helm configuration for LHDI Deployment
4. Miscellaneous Setup

Unless otherwise stated, any team member (including those in the Partner Team) can perform the described tasks.

These tasks set up and configure the resources needed for eventual deployment. For deployment to LHDI, see Partner Team Deploy Process.

References

PRs that add a new domain:

• domain-cc Feature - run contention classification api in docker #1646
• Setup a deployment process/plan for domain-ee in nonprod #1922
• By 8/21: Setup a deployment process/plan for domain-ee in nonprod #1932

PRs that add a new VRO microservices:

• Docker: add svc-bie-kafka container image #1794
• Helm: Add config for svc-bie-kafka #1796

1. Gradle subproject for all domain code

Create a new domain-XYZ folder (replacing XYZ with a name or acronym associated with the Partner Team). In that folder, add build.gradle and README.md with build and test instructions for the domain. Refer to other domain-* folders.

Add a domain application project

In the domain-XYZ folder, create Gradle subproject(s) for your application. The subprojects depend on your application.

• Populate the subprojects with code -- refer to Software Conventions and other domain-* folders; for example:
  • For Java projects, refer to domain-xample.
  • For non-Java projects, the XYZ-app subproject should have build.gradle and gradle.properties files in the domain-XYZ/XYZ-app folder. There can be multiple *-app subprojects in the domain folder.
• Add each subproject to settings.gradle in the project root folder.
• Add unit tests to the subprojects and ensure ./gradlew :domain-XYZ:test executes those tests. Then in .github/workflows/test-code.yml, update and add job steps to run unit tests in the domain by running ./gradlew :domain-XYZ:test.

2. Docker configurations to containerize applications

• For end-to-end and integration tests, add a docker-compose.yml in the domain-XYZ folder (see Docker Compose). It should set up any new containers added in the domain-XYZ folder. Not all subprojects are manifested as Docker container, i.e., some subprojects are used as libraries -- those projects don't need to be added to docker-compose.yml.

• Add container to scripts/image-names.sh the list of IMAGES environment variable. Run ./scripts/image-names.sh to update scripts/image_vars.src, which is used by GH Action workflows (e.g., to build and publish the Docker image to GHCR). Commit both files.

Add container healthcheck

• For each new container, add a healthcheck.
  • Refer to the HEALTHCHECK command in Dockerfile-java or Dockerfile-python within the gradle-plugins/src/main/resources/docker/ folder.
  • Specify the healthcheck_port in domain-XYZ/XYZ-app/gradle.properties. For port numbering convention, see .
• Add a job step to .github/workflows/container-healthchecks.yml that exercises the healthcheck.

Add integration tests

• Add end-to-end and/or integration tests for the domain.
• Add a new GitHub Action workflow that runs those tests. For examples, refer to *-integration-test.yml and *-end2end-test.yml.
• Add the new workflow as a job in .github/workflows/continuous-integration.yml.

Add mock service

If a new mock service is needed, add it to the mocks/ folder. Note that mocks/ is a Gradle composite build (not a Gradle subproject) to isolate it from the typical VRO codebase because the mocks are not built for LHDI deployment. See PR Gradle: refactor mocks into composite build #1704 for details.

Update CI/CD GitHub Action workflows

• For each Python subproject, add the requirements.txt files to .github/actions/setup-vro/action.yml and .github/secrel/config.yml.
• If the domain application is ready for daily deployments to LHDI dev as part of [our CI/CD](CI CD Workflows), then add a job to .github/workflows/continuous-delivery.yml.

3. Helm configuration for LHDI Deployment

• Add a new helm/domain-XYZ/ folder and populate it. Refer to Helm Charts and helm/domain-*/.
  • Ensure that helm/domain-XYZ/templates/named_templates is a symbolic link.
• Add an entry to helmChartAppVersions in build.gradle in the project root folder so that Helm chart version number are updated when a release is created.

Update Deployment GitHub Action workflows

• Add the new helm chart folder as a helm_chart option in .github/workflows/update-deployment.yml.
• Optionally, create .github/workflows/update-deployment-XYZ.yml that deploys to all LHDI environments except prod for Partner Teams to use. Tip: copy and modify existing workflows, e.g. update-deployment-cc.yml and update-deployment-ee.yml.
• In the rare situation where different versions of containers in the same helm chart needs to be deployed, create a new workflow (refer to update-deployment-app.yml) and update deploy.sh (to pass the version numbers to the helm command).

4. Miscellaneous Setup

Optional: domain-XYZ branch

If the Partner Team wants to work on a separate git branch (see ):

• Ask the VRO Team to create a domain-XYZ branch in the repo. It will be a protected branch and is configurable by repo admins at https://github.com/department-of-veterans-affairs/abd-vro/settings/branches.
• Add the branch as a domain_branch option to .github/workflows/fast-forward-develop.yml.

Add entry to API Gateway

To have the OpenAPI spec available via Swagger UI, update configurations for the API Gateway -- refer to which:

• configures the VirtualService
• updates Swagger UI configuration