Skip to content

Latest commit

 

History

History
189 lines (139 loc) · 6.65 KB

BUILD.md

File metadata and controls

189 lines (139 loc) · 6.65 KB
Raw

📦 habitcentric Development Guide

🎈 Welcome to our habitcentric development guide! 👋

We will help you setting up a development environment to build habitcentric's services from source and provide you with general guidelines to work with this repository.

📖 Table of contents

📄 Repository Layout

  • .run - IntelliJ run configurations
  • demos - Scripted interactive demos that showcase specific scenarios, written in bash.
  • docs - Resources like images for our documentation
  • infrastructure - Infrastructure showcases
    • istio - Istio service mesh configuration showcase
    • kubernetes - Kubernetes Deployment showcase
    • kuma - Kuma service mesh configuration showcase
    • linkerd- Linkerd service mesh configuration showcase
    • traefik-mesh - Traefik Mesh service mesh configuration showcase
  • pipeline - CI pipeline configuration
  • services - habitcentric services
    • auth-keycloak - Keycloak distribution containing habitcentric realm & theme configuration
    • habit - Spring Boot Java service
    • track - Spring Boot Java service
    • report - Spring Boot Kotlin service
    • gateway - Spring Cloud Gateway service
  • test - Testing utilities
    • infra-tests - Automated infrastructure tests to test applied service mesh configurations, written with Spock
    • lpt-locust - Load generator to generate requests to habitcentric, written with Locust

💻 Developing habitcentric services

Depending on your personal preference, you can either develop against mock services or develop against the real thing. The mock services are implemented using wiremock.

Some services require a local postgres instance as well. The mock services and postgres instance can be started up using the provided docker-compose.yaml inside of the service directory.

⚠️ You can not start the mock services and the real services simultaneously because they bind to the same port. This is by design, so mock services and real services can be used interchangeably.

All JVM-based services are set up as a Gradle project and can be run using the provided Gradle wrapper as long as you have a JDK 11 present on your machine.

Example: Starting report service using mock services

# change into report service directory
cd ./services/report

# start mock services
docker-compose up -d habit track

# start report service
./gradlew bootRun

Example: Start report service using real habit and track service

# change into habit service directory
cd ./services/habit

# start local postgres instance for habit service
docker-compose up -d db

# start habit service
./gradlew bootRun

# change into track service directory
cd ../track

# start local postgres instance for track service
docker-compose up -d db

# start track service
./gradlew bootRun

# change into report service directory
cd ../report

# run report service
./gradlew bootRun

ℹ️ If your IDE supports starting Spring Boot applications directly, you can use your IDEs run configuration as well.

All other services (currently only auth-keycloak) can be started using the provided docker-compose.yml file. They are configured to build the container image locally, so make sure to provide the --build option to re-build the container.

docker-compose up -d --build

Code Style Conventions

General

We provide an EditorConfig configuration inside the root folder of this repository. This config defines some general rules like indent size, indent style etc. Please make sure that your IDE respects .editorconfig files.

Java

We use the Google Java Style to format Java source code. All Gradle projects include a Spotless plugin configuration you can use to format the code before commiting it.

./gradlew spotlessJavaApply

Google also provides a CLI and integrations for IDEs like IntelliJ IDEA, Eclipse and VS Code. See https://github.com/google/google-java-format.

Kotlin

We use the default IntelliJ Kotlin code style. There are currently no tools configured to enforce code style rules outside of IntelliJ.

Container & Helm Charts

Dockerfiles and Helm charts are maintained in the service directories, either directly in the root directory in case of the Dockerfile or a dedicated helm directory for the corresponding Helm charts.

Container images are published using Docker Hub while Helm charts are currently only available for local use.

🔌 Infrastructure Configurations

All infrastructure configurations, like deployment configurations for different deployment targets or service mesh config files are stored in the infrastructure directory.

The goal is to provide infrastructure configurations which...

  • ... provide a good out-of-the-box experience, i.e. can be applied from scratch without much issues
  • ... are easily destroyable, i.e. all deployments can be removed entirely with a single command

ℹ️ This is one of the reasons why we do not utilize or showcase any Kubernetes operators. Operators need time to destroy deployments before they are destroyed themselves.

⚙️ Pipeline

⚠️ This section is work in progress due to our GitHub migration.

♻️ Miscellaneous Stuff

Service Port Configuration

Each habitcentric service runs with the same ports across all deployment options.

Service Port
gateway 9000
habit 9001
habit-postgres 10001
track 9002
track-postgres 10002
report 9003
ui 9004
keycloak 8080
keycloak-postgres 10003
kafka 11001 - 11003
kafka-ui 11001 - 11003