Build and run ODD Platform

Developer guide on how to build and run ODD Platform backend and frontend

For instructions on how to run the ODD Platform and ODD Collectors locally in a Docker environment, please follow Try locally article.

ODD Platform tech stack

ODD Platform tech stack is:

• Backend

  • Java

  • Gradle

  • Spring WebFlux

  • jOOQ

  • Flyway for database migrations

  • Testcontainers for integration testing

• Frontend

  • Typescript

  • React

ODD Platform's backend and frontend are packaged inside one JAR, which is packaged inside one Docker container using JIB.

We believe in contract-first approach. That's why ODD Platform uses OpenAPI generators and jOOQ custom generator over database migrations to create models which are used further in the code.

Prerequisites

• Docker Engine 19.03.0+
• preferably the latest docker-compose
• Java 17 (consider using SDKMAN for that)
• Node 18.16.0 and pnpm 8.4.0 (consider using nvm for that)

Build ODD Platform

Fork and clone a repository if you haven't done it already.

git clone https://github.com/{username}/odd-platform.git

Go into the repository's root directory

cd odd-platform

Build ODD Platform into JAR file

Use gradle wrapper to build the platform

./gradlew clean build

Building a project is a good way to check if your code compiles, all tests pass, there's no code smells, etc.

Build ODD Platform into Docker container

Use gradle wrapper to build the platform and containerize it

./gradlew clean jibDockerBuild --image odd-platform:dev -PmultiArchContainerBuild=false

The above command will build a platform and create a local docker container called odd-platform:dev. If you want to change the image name, feel free to change an --image property to what you want.

Above commands will not only build ODD Platform into JAR or Docker container, but also run tests and checkstyle validations. If you want to remove this behaviour, add following properties to the end of a command:

• -x test — for disabling test runs

• -x checkstyleMain -x checkstyleTest — for disabling code checkstyle validations

Gradle's clean task deletes generated OpenAPI and jOOQ models and invalidates gradle's build cache, which causes slower builds. If you are not changing an odd-platform-specification OpenAPI and not developing database migrations, the best approach would be to not run this task. Just omit clean word in your commands

Run ODD Platform locally

All commands must be executed in the project's root directory

The easiest way to have ODD Platform at your disposal locally is to:

Launch a PostgreSQL docker container as a ODD Platform's database using docker-compose

docker-compose -f docker/demo.yaml up -d database

Start the application

./gradlew bootRun

Inject some demo metadata into your local ODD Platform.

You'd need to install Python 3.8+ in order to run this.

PLATFORM_HOST_URL=http://localhost:8080 APP_PATH=./docker/injector python docker/injector/inject.py

Now you should have ODD Platform with demo metadata injected at your disposal at http://localhost:8080. If you want to reconfigure default settings, please take a look at Configure ODD Platform page.

Run ODD Platform as a frontend engineer

We understand that frontend engineers might not want to install heavy prerequisites such as Java only for make changes in the UI. Here is one of the ways how to run fully functional ODD Platform in Docker:

Launch Docker container with ODD Platform, database and inject demo metadata using docker-compose:

docker-compose -f docker/demo.yaml up -d odd-platform-enricher

Or if you want to have the latest platform version from main or any branch, build it and replace odd-platform image with created one in docker/demo.yaml compose file and run it using command above:

odd-platform:
  image: <Put your image here>
  restart: always
  environment:
    - SPRING_DATASOURCE_URL=jdbc:postgresql://database:5432/${POSTGRES_DATABASE}
    - SPRING_DATASOURCE_USERNAME=${POSTGRES_USER}
    - SPRING_DATASOURCE_PASSWORD=${POSTGRES_PASSWORD}
  depends_on:
    - database
  ports:
    - 8080:8080

Go into UI folder

cd odd-platform-ui

Run UI development server

VITE_DEV_PROXY=http://localhost:8080/ pnpm start

Now you should have UI development server at your disposal at http://localhost:3000

Run ODD Platform test

To run backend tests simply execute the following command:

./gradlew test

To run frontend tests execute the following command in odd-platform-ui folder:

pnpm test