Skip to content

Local Setup

Jump to bottom
Julius A edited this page Dec 6, 2024 · 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 (Community Edition):

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

See Ubuntu VM Setup for detailed software setup instructions on Ubuntu.

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 | Other OS Guide)
    • Java Setup instructions using brew & jenv

      Note: You can use either jenv or sdk to manage multiple java versions on Mac. DO NOT use brew for java version management. Brew is a package manager and not meant for dedicated language version management.

      1. brew install openjdk@17
      2. Add java versions to your PATH; follow brew instructions
      3. brew install jenv
      4. export PATH="$HOME/.jenv/bin:$PATH" eval "$(jenv init -)"Add jenv to your shell
      5. source ~/.zshrc # or ~/.bash_profile, ~/.bashrc, etc. Source and apply changes
      6. jenv add /usr/local/opt/openjdk@11Add java versions to env, this path may be different depending where home-brew keeps your java binaries
      7. jenv local 17 Set global/local java versions. Use local in abd-vro repository, or set global for system-wide java versioning
      8. java -version Verify java has been setup

    • ⚠️ If you are using MAC: Be very careful here! LHDI guide is outdated, running ./scripts/mac-devtools.sh will generate errors. Adoptopenjdk is deprecated (Use openjdk instead) and code climate repositories have been moved.

  • Python (latest version or 3.10.12 - see this page for setup)
  • Gradle 8.1.1. Better yet, use ./gradlew
  • docker (ensure docker-compose version 2.X)

Note for Apple Silicon Macs: export DOCKER_DEFAULT_PLATFORM=linux/amd64 Note that you do not need to install Docker Desktop only the docker command and a container runtime manager which can be Docker Dekstop but could also be something like colima

Recommended Kubernetes GUI

First, generate a kubeconfig file using the Lightkeeper Tool from within the VA network (CAG).

Once you have gotten a config file to your development machine, the VRO Team recommends Lens app as the preferred UI for interacting with LHDI. Important: Lens used to be an open-source project. However, the rights to it were purchased in late 2023, and the process of obtaining a personal license seems to have been removed from their website. The good news is that you can still subscribe with a personal license for free using the following steps:

  1. Login with or sign up for a Lens ID via https://k8slens.dev/.
  2. Keep your logged-in tab open to ensure your login remains active for the remainder of the steps.
  3. Opening a new tab, go to https://app.k8slens.dev/subscribe/personal/login and re-enter your Lens credentials
  4. Upon successful login, you have now subscribed with a personal license which has been added to Lens ID you used in step one.

It is possible this is a recent bug that the company introduced accidentally, but it is more likely an intentional step to reduce the use of personal licenses. I've found no other way to reach this subscription page but fortunately someone on Reddit still knew the URL.

LHDI has additional setup documentation for Mac OS and Other Operating Systems.

Please note, this type of visibility of the production kubernetes environment is limited to authorized members of the core VRO team, per risk management precautions related to the ATO. Partner teams do not have this level of access.

GitHub Permissions

This should no longer be needed:

  • Create a GitHub personal access token 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>

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

Running the Applications

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 services in your local environment by navigating to the root of your application directory and running the following commands:

./gradlew clean
# Note: Due to the way Gradle computes dependencies, the `clean` command must always be separate from `build` commands
./gradlew build check docker

This will build all the application artifacts and docker images.

Troubleshooting: Flake8 is a linter used to validate python files against a style guide. It's been observed that the gradle build can fail due to the way linting is performed when using a version of python other than 3.10.12 - if this is the case, install pyenv and use it to manage your python version. See here for instructions.

You can then start the services by running (more details at Docker Compose):

source scripts/setenv.sh
COMPOSE_PROFILES="all" ./gradlew dockerComposeUp # NOTE: more options here: https://github.com/department-of-veterans-affairs/abd-vro/wiki/Docker-Compose#platform-base--java-app-with-platform-microservices

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

This should bring up several docker containers, including svc-bip-api running at http://localhost:10401.

Troubleshooting: you may need to execute COMPOSE_PROFILES=svc or COMPOSE_PROFILES=all if the gradlew command fails. This variable is used to determine which services to start. For more information read the Docker Compose wiki page.

Verifying Containers are Running

Use docker ps -a to view information on your containers. docker ps -a or the Docker Desktop app should show a number of running containers including vro-rabbitmq-service, vro-postgres-service, svc-bip-api, and others. Use Docker Desktop or docker logs {container ID} to view container logs.

You can verify that the services are running by querying the health check endpoint for the services. Using svc-bip-api as an example:

curl http://localhost:10401/actuator/health

You should get back a response similar to the following:

curl http://localhost:10401/actuator/health

{
    "status": "UP",
    "components": {
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 62671097856,
                "free": 49476235264,
                "threshold": 10485760,
                "path": "/app/.",
                "exists": true
            }
        },
        "livenessState": {
            "status": "UP"
        },
        "ping": {
            "status": "UP"
        },
        "rabbit": {
            "status": "UP",
            "details": {
                "version": "3.12.14"
            }
        },
        "readinessState": {
            "status": "UP"
        }
    },
    "groups": [
        "liveness",
        "readiness"
    ]
}

Other Domains

domain-cc

With the above supporting services running, use gradlew to start the domain-cc app:

./gradlew :domain-cc:dockerComposeUp

Verify cc-app is running:

curl http://localhost:8120/health

You should get a response similar to the following:

{"status":"ok"}
domain-ee

Use gradlew to start the domain-ee services:

./gradlew :domain-ee:dockerComposeUp

Verify max-cfi-app (port 8130) and ep-merge-app (port 8140) are running:

curl http://localhost:8130/health
curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"diagnostic_codes": [6260]}' \
  http://localhost:8130/max-ratings
curl http://localhost:8140/health

You should get a response similar to the following:

{"status":"ok"}
{"ratings":[{"diagnostic_code":6260,"max_rating":10}]
{"status":"healthy"}

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 dockerComposeUp every time.

  • Refer to Docker Compose
  • Find instructions for setting up a jetbrains run configuration for vro-app-1 HERE.

Tips

Refer to Running Kafka Services/Tests Locally for information on how to run the bie-kafka microservice(s), specifically helpful for when there are issues with our messing system.

  • RabbitMq occasionally segfaults during startup if using apple silicon. Restarting the container will resolve this issue.
  • Check if the svc-bie-kafka docker container is running and causing failures in mock-bie-kafka:dockerComposeUp, if not restart it.

If you are having issues installing ruby3.3.0 there might be an openssl issue. Run the following commands to fix it.

brew install openssl@3 rvm install 3.3.0 --with-openssl-dir=$(brew --prefix openssl@3)

Contributing

To contribute to VRO repos, you need to perform additional setup. For additional steps, see the Development Process Wiki.

WIP

Breakdown of RabbitMq Messaging, Exchanges, queues, and routes

Clone this wiki locally