Skip to content

LHDI's Boilerplate Instructions

Jump to bottom
greene858 edited this page Feb 15, 2023 · 11 revisions

VRO software is deployed on the Lighthouse Delivery Infrastructure (LHDI) platform, which offers tools, services, and support team.

LHDI's Java Starter Kit was used to populate this codebase (see PR #8) using Java (AdoptOpenJDK) 17 and Gradle 7.4.

LHDI's Boilerplate Setup Instructions

About

This is a Java Spring Boot application that has been created using the Lighthouse DI Java 17 Starterkit. It is intended to be used as a starting point for building Java APIs and should be customized to deliver whatever functionality is required. If no other changes have been made, this application will have these features included by default.

Getting Started

Required Dependencies

Before you run this application locally, you will need to make sure you have all the following required dependencies available in your local environment:

Use the Mac OS Guide to make sure you have all the above dependencies available in your local environment. No need to clone the starterkit repo, use ./scripts/mac-dev-tools.sh included in this repo. Otherwise, refer to the Other Operating Systems Guide.

You will also need to have a GitHub personal access token with the read:packages permission exported in your local shell. This is required to in order to download application artifacts that are published to the VA GitHub Package Registry.

You can generate a new access token by following this guide. When you have your token, make sure it is available in your local shell by running:

export GITHUB_ACCESS_TOKEN=<replace-with-token-from-github>

You will also need to be added to the VA-ABD-RRD GitHub team.

Running the Application

Once you have all the required dependencies, you can start the application in your local environment by navigating to the root of your application directory and running the following command:

./gradlew clean
./gradlew build check docker

This will build all the application artifacts and docker images.

Note: Due to the way Gradle computes dependencies, the clean command must always be separate from build commands

You can then start the application by running:

./gradlew :app:dockerComposeDown :app:dcPrune :app:dockerComposeUp

This should bring up a docker container with the app running at http://localhost:8081

There are shortcut tasks defined in the root build.gradle file to make life a bit easier:

./gradlew devloop     # rebuild what is out of date, recreate and restart individual docker images
./gradlew restartloop # stop containers, then proceed with `devloop`
./gradlew resetloop   # stop containers, clean volumes, then proceed with `devloop`

The devloop is most convenient and quickest feedback cycle if one needs to do manual testing with the system services.

Note that at this time, ./gradlew run and ./gradlew bootRun require additional setup with database dependencies prior to use with a local development environment.

Verifying the Application is Running

You can verify that the application is up and running by issuing the following commands in your terminal:

curl localhost:8081/health
curl localhost:8081/actuator/info

You should get back responses similar to the following:

curl localhost:8081/health

{
    "status":"UP",
    "components":{
        "db":{
            "status":"UP",
            "details":{
                "database":"PostgreSQL",
                "validationQuery":"isValid()"
            }
        },
        "diskSpace":{
            "status":"UP",
            "details":{
                "total":62725623808,
                "free":53279326208,
                "threshold":10485760,
                "exists":true
            }
        },
        "livenessState":{
            "status":"UP"
        },
        "ping":{
            "status":"UP"
        },
        "readinessState":{
            "status":"UP"
        }
    },
    "groups":[
        "liveness",
        "readiness"
    ]
}
curl localhost:8081/actuator/info

{
    "app": {
        "description": "Java API Starter from Template",
        "name": "abd_vro"
    }
}

CI/CD Pipeline

This project comes with a skeleton Github Actions CI/CD pipeline out of the box. You can always choose to rewrite the pipeline using a different CI/CD tool; this pipeline serves as an example that you can use and run with minimal setup.

Secrets

In order to run the pipeline, you will need to create a personal access token and add it to your repository's secrets in Github. The access token should have write:packages scope.

The secrets you need to configure are

  • ACCESS_TOKEN: the personal access token
  • USERNAME: the Github username of the user who owns the access token

Default Pipeline Behavior

The default pipeline has 3 jobs, which do the following things:

  • Runs CIS benchmark tests against the application Docker image using docker-bench-security
  • Builds and tests application
  • Publishes Docker image to VA GHCR repository

Dependencies

The pipeline runs on Github's ubuntu-latest runner, which is currently Ubuntu 20.04. The Github Actions Ubuntu 20.04 documentation lists the software installed by default. To learn more about choosing a Github runner and Github-hosted runner types, see the job.<job-id>.runs-on documentation.

Software required for the pipeline but not installed by default, such as Java 17, hadolint, and spectral, is installed in the pipeline. The installation for app build dependencies is implemented as an action in <./.github/actions/setup-pipeline/action.yml>.

Deploying the Application

The pipeline does not currently deploy the application to the DI Kubernetes clusters out of the box, although this setup will be coming in the future. To learn how to deploy your applications, see the DI ArgoCD docs.

Common Errors

  1. Error: Cannot find plugin

    Error Message:

    * What went wrong:
Plugin [id: 'gov.va.starter.plugin.cookiecutter', version: '0.1.20', apply: false] was not found in any of the following sources:

- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (could not resolve plugin artifact 'gov.va.starter.plugin.cookiecutter:gov.va.starter.plugin.cookiecutter.gradle.plugin:0.1.20')
Searched in the following repositories:
    MavenLocal(file:/Users/aasare/.m2/repository/)
    Gradle Central Plugin Repository
    MavenRepo
    BintrayJCenter
    maven(https://palantir.bintray.com/releases)
    maven2(https://dl.bintray.com/adesso/junit-insights)
    starterBootPkgs(https://maven.pkg.github.com/department-of-veterans-affairs/lighthouse-di-starter-boot)
    nexus(https://tools.health.dev-developer.va.gov/nexus)

    Fix: Set your Github token as per the instructions in the Required Dependencies section above.

  2. Error: Failed to get resource

    Error Message:

    Failed to get resource: GET. [HTTP HTTP/1.1 401 Unauthorized: https://maven.pkg.github.com/department-of-veterans-affairs/lighthouse-di-starter-boot/starter/java/build-utils-property-conventions/starter.java.build-utils-property-conventions.gradle.plugin/0.1.32/starter.java.build-utils-property-conventions.gradle.plugin-0.1.32.pom)]

    Fix: Set your Github token as per the instructions in the Required Dependencies section above, ensure that read:packages is true.

What's Next

Once you have verified that you are able to run the application successfully, you can now start customizing the application to deliver the functionality you would like.

By default, this application assumes the use of a build, test, release cycle as defined in this development guide. Take a look at that guide to see how you can make changes, test them and get them deployed to a target environment.

The application itself is organized into the following three tiers of functionality:

  • API
  • Service (business logic)
  • Persistence

To see how each of these tiers is used by default, take a look at the Project Structure documentation.

Clone this wiki locally