This is the application template for serverfull applications.

• Requirements
• Quick Start
• Java Version
• Docker
• Localstack
• Tests
• Migrations with Flyway
• Swagger

• Java 17
• Docker
• Docker Compose

To run the application use the following steps:

1. Build the application

   ./gradlew clean build

2. Start external dependencies

   docker-compose up -d

3. Run database migrations

   ./gradlew migrateLocal

4. Start the application

   ./gradlew bootRunDev

If the linter breaks you can run ./gradlew ktlintFormat to auto-fix the problems.

In order to facilitate the Java version management we recommend using SDKMAN as the JDK version management tool.

After installing it, run:

sdk install java 17.0.3-ms # as of time of writing this version is working, but fell free to try different distributions
sdk use java 17.0.3-ms # if is not already set as default

And everything should work as expected.

Since the end of 2021 the most popular way of running Docker containers on Mac, Docker Desktop, became a paid service for companies of medium and large size. Given that, as an alternative way of running docker-compose, we recommend using colima for a minimal setup of the docker daemon.

First we need to install colima to run the docker daemon. In order to do that Homebrew is a pre-requisite.

After installing Homebrew just run:

brew install colima

After that we need to install the docker CLI, so we can interact with the daemon:

brew install docker
brew install docker-compose

Lastly we just need to start the daemon and use docker as we would normally

colima start
docker-compose up -d # should work normally

Localstack is used to mock AWS resources. After running the docker-compose up you can interact with the service in the following ways:

You can create resources after the Localstack container is up by adding shell-scripts to the shell-scripts/localstack folder.

These scripts can use the aws local CLI to create resources (packaged with the Localstack image) and should follow the naming convention XX_script_description.sh, like the examples 01_create_queues.sh and 02_create_topics.sh. They will be executed in ascending order.

After running the Localstack container you can directly interact with it via the aws CLI (or the aforementioned awslocal).

First you need to download and configure the CLI:

brew install awscli
aws configure

When asked for secret key and access key, you can just write any string (localstack won't check).

You can use the following command to send a SQS message.

Modify the --messsage-body to the payload you are testing.

Modify the --queue-url to the name of the queue you are testing.

aws sqs send-message \
  --queue-url http://localstack:4566/queue/user-queue-event-dev \
  --endpoint-url http://localhost:4566 \
  --message-body '{
    "event": "CREATED",
    "uuid": "0ee8a656-ed76-11ec-8ea0-0242ac120002"
  }' \
  --message-attributes '{ "contentType":{ "DataType":"String","StringValue":"application/json" } }'

If you are running the application, it will already start consuming the message you just sent. You can also check the message you just sent with the command:

aws sqs receive-message \
  --queue-url http://localstack:4566/queue/user-queue-event-dev \
  --endpoint-url http://localhost:4566

Modifying the --queue-url parameter with the queue name you are testing.

To run tests with coverage use

./gradlew jacocoTestReport

For the repository ITs we are using H2 Database for simplicity (since Hibernate abstracts this to us no change in the code needs to be made to run the tests).

As a good practice these kinds of tests should always have the @Rollback annotation to correctly reset the DB after each run.

Beyond that you can add your own scripts to populate the database with the @Sql annotation on the src/test/resources/sql folder.

Migration files should be placed at src/main/resources/db/migration.

To run the migrations use ./gradlew migrateLocal.

We use Swagger v3, an OpenAPI implementation, to document our endpoints. To access the documentation just run the project and go to http://localhost:8080/swagger-ui.html

• Kotlin - Programming language
• Gradle - Build automation tool
• Spring - Comprehensive programming and configuration model for modern JVM-based applications
• Spring Boot - Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications
• Ktlint - Linter for Kotlin
• Detekt - Static code analyzer for Kotlin
• JaCoCo - Code coverage
• MockK - Mocking library for Kotlin
• Hibernate ORM - Database ORM and auditing features
• AWS Spring - AWS SDK and Spring Boot integration
• Swagger - REST API documentation
• Flyway - Database migration tool