Skip to content

Local Setup

Jump to bottom
Mason Watson edited this page May 1, 2023 · 33 revisions

If you are on a Windows machine, take a look at Setup on Windows first.

IDE

VRO is architected to be language agnostic though you should always confirm with maintainers that a language is supported before using it.

If a language is supported, you should feel free to use your preferred IDE for your language. However, it is recommended to use an IDE which supports an integration with Gradle (VRO's build system), like IntelliJ.

Required Dependencies

Directory setup

Make sure you have both abd-vro and abd-vro-dev-secrets cloned in sibling directories.

path/to/code/
         |-----abd-vro/
         |-----abd-vro-dev-secrets/

Software Packages

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

  • Java 17 ([Mac Guide][6] | [Other OS Guide][5])
  • Gradle 7.2, 7.4 (to be compatible with Java 17), 7.5
  • [docker][7]

Note for Apple Silicon Macs: export DOCKER_DEFAULT_PLATFORM=linux/amd64

  • [hadolint][8]
  • [spectral][12]
  • [shellcheck][9]

LHDI has additional setup documentation for [Mac OS][4] and [Other Operating Systems][5].

GitHub Permissions

  • Create a GitHub [personal access token][11] with read:packages permission.
  • Add the newly created token to your shell
# add this to your shell profile (e.g. ~/.zprofile)
export GITHUB_ACCESS_TOKEN=<replace-with-token-from-github>
  • This is required to in order to download application artifacts that are published to the [VA GitHub Package Registry][10].
  • You will also need to be added to the [VA-ABD-RRD GitHub team][15].

Running the Application

You'll need port 5432 (default for postgres) available/not-in-use when running the code.

Also, be sure that you have a docker daemon running on your machine. If you use Docker Desktop, having the application running will run the daemon. However, if you are using a different Docker runtime like Colima, you will need to manually start the daemon process configure it to always run at boot time.

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

Note: Make sure you have completed the instructions in the abd-vro-dev-secrets README

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"
    }
}

Running app container locally

The above instructions should give you enough to get all the necessary docker containers running to test new functionality in abd-vro. However, developers may wish to run the vro-app-1 container with a run configuration to more quickly iterate on changes being made as opposed to performing a full ./gradlew :app:dockerComposeDown :app:dcPrune and ./gradlew :app:dockerComposeUp every time.

  • Find instructions for setting up a jetbrains run configuration for vro-app-1 HERE.
Clone this wiki locally