Runbook for local development

May 26, 2024 · View on GitHub

This project uses Quarkus, the Supersonic Subatomic Java Framework and ReactJS.

Development

This project requires at least:

  • Java 17 + Maven
  • NodeJS 18+
  • Docker 20+
  • Yarn

Setup

With Homebrew

Use the Brewfile for all necessary dependencies:

brew bundle && make bootstrap

Linux - without Homebrew

Ensure you have the following tools installed:

Start local dev environment

There is a Makefile to ease the initial setup.

  1. Make sure you have the very base setup if you run this the first time.
make dev
  1. Start the backend
make backend

NOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/. The actual UI of Tapir is accessible via http://localhost:8080. Source can be found under src/main/webui

  1. Test using the example Terraform code in example. You need to upload a module and a provider with the identifiers that are specified within the code.
make terraform

Clean everything

This will ensure a clean state, where you need to run bootstrap again.

make clean

Packaging and running the application

The application can be packaged using:

./mvnw package

It produces the quarkus-run.jar file in the target/quarkus-app/ directory. Be aware that it’s not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.

The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.

Adding new configuration parameters

Apart from the application.yml file, you should add the new configuration parameters to the official Helm chart of Tapir. The configuration documentation should be updated in the respective README template and in the values.yaml.

Adding new API routes

Tapir needs to make use of a workaround to overcome routing issues with Quarkus since 3.9 and Quinoa. The workaround is to add the new route to PATH_PREFIXES list in the Router class. For more details see comments in the class.

  • Elasticsearch REST client (guide): Connect to an Elasticsearch cluster using the REST low level client
  • Quarkus Quinoa (docs): Quinoa is a Quarkus extension which eases the development, the build and serving single page apps or web components
  • Quarkus AWS Services (docs): Quarkus implementation of the AWS Java SDK
  • Azurite Storage (docs): Azure Blob Storage emulator