example-spring-loyalty

Pipeline	Status
Continuous integration
Daily security checks

Example application loyalty program powered by Spring Boot

Directory structure

Here is the basic skeleton for your app repo that each of the starter templates conforms to:

├── .buildkite
├── api-service
│   ├── src
│       ├── integration-test
│       ├── main
│       ├── test
│   ├── build.gradle # Define app dependencies here
│   ├── Dockerfile
│   ├── helm
├── batch-job
│   ├── src
│       ├── integration-test
│       ├── main
│       ├── test
│   ├── build.gradle # Define app dependencies here
│   ├── Dockerfile
│   ├── helm
├── config
│   ├── checkstyle
│   ├── codestyle
├── gradle
│   ├── wrapper
├── performance-test
├── docker-compose.yml
├── docker-compose-buildkite-agent.yml
├── docker-compose-local.yml
├── .envrc.template
├── build.gradle # Define global dependencies here

• Your app's source code is nested beneath the api-service directory. It composes of submodule for main logic, unit testing, and integration testing. Note that for app-specific dependencies, it is recommended to configure in build.gradle within this directory.

• You can configure coding standards, dependency vulnerability checks in config directory. I already provided checkStyle with simple Java rules.

• For compatibility with Kubernetes, Simple Helm chart is located in helm directory. However, other Kubernetes dependencies (e.g. spring-cloud-starter-kubernetes) is not included within this template. Please kindly add it if necessary.

• Your app's performance testing scripts, written in Scala, is nested beneath the perfomance-test directory. Please follow the Gatling DSL guideline here.

• It is also recommended updating docker-compose-local.yml if your app requires external components, such as database, and message queue to test locally.

• The build.gradle in root path is used for defining global configuration. In this case, I provided simple SonarQube and Docker build & publish plugins.

• The Buildkite CICD pipeline script can be found beneath the .buildkite directory. The build step specifications are based from docker-compose.yml.

Prerequisites

In Buildkite managed secrets S3 bucket, create a new folder called example-spring-loyalty. Then, create a new file called env with the following credentials:

export GITHUB_USERNAME=<your-github-username>
export GITHUB_TOKEN=<your-github-token>
export DOCKER_USERNAME=<your-docker-hub-username>
export DOCKER_PASSWORD=<your-docker-hub-password>

Development guidelines

Starting local server

Install Homebrew formulae direnv that can load and unload environment variables depending on the current directory.

Then, clone .envrc.template with:

$ cp .envrc.template .envrc

Fill environment variables in .envrc, then load environment variables by running:

$ direnv allow

Finally, start local server on local active profile by running:

$ docker-compose -f docker-compose-local.yml up -d && ./gradlew clean api-service:bootRun

$ docker-compose -f docker-compose-local.yml up -d && ./gradlew clean batch-job:bootRun

For other active profiles, specify profile on System property as:

$ ./gradlew clean api-service:bootRun -Dspring.profile.active=<your-profile-name-comma-separated>

Compile and Build

The default Spring active profile is set to local, add -Dspring.profiles.active=<your-custom-profile> to customise the active profile.

$ ./gradlew clean build

To specify module in order to run Gradle tasks:

$ ./gradlew api-service:clean api-service:build

$ ./gradlew batch-job:clean batch-job:build

Run mutation testing

References: PIT Mutation Testing

We use PIT to run our unit tests against automatically modified versions of the application code. When the application code changes, it should produce different results and cause the unit tests to fail. If a unit test does not fail in this situation, it may indicate an issue with the test suite.

$ ./gradlew pitest

Style Guide

Since it is much easier to understand a large codebase when all the code in it is in a consistent style, we use IntelliJ Java Google Style where you can import to IntelliJ by navigating to Preference > Editor > Code Style > Java, then click on Kebab Menu and Import Scheme. Finally, browse to the XML file underneath config/codestyle.

Environment variables

We use direnv that can load and unload environment variables depending on the current directory, so that you don't have to export variables repetitively.

After finish installation, copy .envrc based from .envrc.template and fill all required variables, then run this following command in the root directory to apply variables:

direnv allow

Git hooks

We use ghooks.gradle for Git hooks Gradle plugin.

To download Git hooks plugin, run:

./gradlew your-module:clean your-module:build

API documentation

See available API endpoints in Swagger UI.

CICD

Buildkite is a platform for running fast, secure, and scalable continuous integration pipelines on our own infrastructure, it even works with a local Docker engine. Although buildkite agent doesn't have dedicated agent for Java / Gradle, yet it allows builds to use Docker ( for more details, read this documentation.)

Please be careful that you have to start buildkite-agent in local machine in order to use Buildkite.

Install buildkite-agent based on your own machine. Follow the instructions here. The snippet below is the example for macOS using Homebrew:

brew install buildkite/buildkite/buildkite-agent

Then, you have to set Buildkite agent token for this pipeline, you can either run this command below or use direnv by creating .envrc based from .envrc.template:

export BUILDKITE_AGENT_TOKEN=<your-buildkite-agent-token-here>

Finally, run buildkite-agent via docker-compose with the following command:

docker compose -f docker-compose-buildkite-agent.yml up

Deployment

Each module contains Helm chart located in helm directory. To install/upgrade Helm chart, run:

helm upgrade --install example-spring-loyalty-<module-name> <module-name>/helm --set image.tag=<your-semantic-version>