- 📘 Introduction
- 👾Tech Stack
- 📋 Requirements
- 🛠️ Project Setup and Configuration
- 🧑🔧🏃 Build and Run the App
- 🧑💻 Testing the App Using the Endpoints
- 📚 References
This app is a simple showcase of a containerized REST API Java backend using Spring Boot, a relational database and modern development practices like automated testing. 🧑🎨🙌
- Create, read, update, and delete (very! 😏) simple AppInfo objects in the database! 🤯
- RESTful endpoints
- Examples of automated integration- and unit tests
- Containerized setup
To save an object, send a JSON like this to the POST endpoint:
{
"version": "0.0.1",
"description": "A bare skeleton of an app."
}
- The REST controller receives the JSON.
- It converts the JSON to an AppInfo object.
- The object is passed to a service.
- The services has access to a repository that can persist the object with an auto generated, sequential ID in the database.
💡 Side Note:
For a sketch of a different approach: Namely, autogenerated UUID's (useful for distributed systems) see the Note class and the script to ensure UUIDv7 generation on the database level.
All other operations work in a similar way.
As recommended entry points to the code, check out the Docker Compose file, the AppInfo class or the ITAppInfoControllerSpec integration test.
-
Build & Dependency Management
- ⚙️ Gradle 8.14: Build automation and dependency management
-
Languages
- ☕ Java 21.0.7: Primary backend language
- 🐴 Groovy 3.0.21: Scripting and testing
- 🐚 Shell Script: Automation scripts for setup and utilities
-
Frameworks & Libraries
- 🌱 Spring Boot 3.5.0: Application framework
- 🧛♂️ Spock 2.4-M6: Testing framework
- 🐘 Hibernate 8.0.1: Object-Relation Mapping for data persistence
- ✍️ Lombok 1.18.38: Boilerplate code reduction
-
Containerization & Orchestration
- 🐳 Docker 28.2.2: Containerization platform
- 📦 Docker Compose 2.36.2: Multi-container orchestration
-
Database
- 🐬 MariaDB 11.4.7: Relational database
To build and run the project you need the following software installed and available in your systems PATH.
- Docker 28.2.2, build e6534b4
- Docker Compose 2.36.2
- MariaDB 11.4.7
- Java SDK 21.0.7
- IDE of your choice for Java/Groovy development
- Clone this repository to your local machine and open it in your favorite IDE.
2.1. Create Environment Variables File
- Copy template.env to
.envin the project root directory. - Edit
.envto set your local credentials and configuration.
2.2. Create Default Spring Profile
- Copy template-application.properties to
src/main/resources/application.properties. - Update properties as needed.
2.3. Create Debug Spring Profile
- Copy debug-application.properties to
src/main/resources/templates/template-application-debug.properties. - Update properties as needed.
2.4. Create Integration Test Spring Profile
- Copy template-application-integration.properties to
src/test/resources/application-integration.properties. - Adjust settings for integration testing.
💡 For all templates: Follow the instructions inside each file to complete your configuration.
2.5. Set Gradle JDK Path
- Open
gradle.propertiesand change:
org.gradle.java.installations.paths={AbsolutePathToYourJDK}
- Ensure MariaDB is running on port
7306(see 🐬 How-To: Change MariaDB Port). - If using a different port, update the value in
application-integration.properties(e.g.,jdbc:mariadb://localhost:{yourPort}).
- Follow 🐬 How-To: Setup custom data directory in 🐬 MariaDB-Help to configure a local Docker volume for data persistence.
- Make sure Docker and Docker Compose are installed and running.
- If you encounter issues (😬) you can consult 🐳 Docker-Help (which also includes links to maintenance scripts).
6.1. Goto the directory of the create-and-run-app.sh script
cd scripts/
6.2. Make it executable with the terminal cmd:
chmod +x create-and-run-app.sh
💡 Side note: Inside the script are some additional config options and deactivated commands for troubleshooting (but highly recommended to leave those untouched! 😉).
1. 🚀 Run the Build Script
- To perform a normal build run:
./create-and-run-app.sh - To perform a complete clean build run:
./create-and-run-app.sh clean
- Gradle generates an HTML report for integration and unit tests.
- View the report here: 👉
build/reports/tests/test/index.html
After executing the script this is what you should see if everything went well:
The following section lists the commands for the command line tool curl to test the app.
But you could also use a more visual tool like Postman if you like.
This will create the entity you send in the database.
-
Verbose curl cmd with response:
curl -v -i -X POST http://localhost:9007/showcase-api/appinfo -H "Content-Type: application/json" -d '{"version": "0.0.1", "description": "A bare skeleton of an app."}'
This will send you the entity you specified by its id from the database.
-
Verbose curl cmd with response (for ID=1):
curl -v -i -X GET http://localhost:9007/showcase-api/appinfo/1
This will send you a list of ALL entities from the database.
-
Verbose curl cmd with response:
curl -v -i -X GET http://localhost:9007/showcase-api/appinfo
This will update the entity you specified by its id in the database with the entity you send.
-
Verbose curl cmd with response (for ID=1):
curl -v -i -X PUT http://localhost:9007/showcase-api/appinfo/1 -H "Content-Type: application/json" -d '{"version": "0.0.2", "description": "A skeleton of an app that wastes up to 250mb!"}'
This will delete the entity you specified by its id in the database.
-
DELETE url: http://localhost:9007/showcase-api/appinfo/1
-
Verbose curl cmd with response (for ID=1):
curl -v -i -X DELETE http://localhost:9007/showcase-api/appinfo/1
- This manual was heavily inspired by the guidelines and best practise examples of: https://github.com/matiassingers/awesome-readme?tab=readme-ov-file