Lightweight RESTful API with Spring Boot 3, Keycloak 21, Docker, PostgreSQL, JPA, Lombok, OpenAPI, etc.

How it works:

1. Docker. First, you need to install docker

• Download Docker Here. Hint: Enable Hyper-V feature on windows and restart;
• Then open powershell and check:

docker info

or check docker version

docker -v

or docker compose version

docker-compose -v

2. Spring boot app

• Clone the repository:

git clone https://github.com/OKaluzny/spring-boot-docker-postgres.git

• Build the maven project:

mvn clean install

• Running the containers:

This command will build the docker containers and start them.

docker-compose up

or

This is a similar command as above, except it will run all the processes in the background.

docker-compose -f docker-compose.yml up

Appendix A.

All commands should be run from project root (where docker-compose.yml locates)

• If you have to want to see running containers. Checklist docker containers

docker container list -a

or

docker-compose ps

Screenshot with runnings containers

3. Keycloak

Create Initial Admin User go to http://localhost:8080/auth and fill in the create initial admin form with username as admin and password as the Pa55w0rd.

Keycloak — Create Initial Admin

Click Create and proceed to administration console and then login with your created initial admin.

Keycloak — Log In Admin

The first screen Keycloak shows after login is the Master realm details.

Keycloak — Master Realm Details

3.1 Create a Realm

Let’s name our first realm automobile:

Keycloak — automobile

3.2 Create a Role

Roles are used to categorize the user. In an application, the permission to access resources is often granted to the role rather than the user. Admin, User, and Manager are all typical roles that may exist in an organization.

To create a role, click the “Roles” menu on the left followed by the “Add Role” button on the page.

Keycloak — Add Role

3.3 Create a User

Keycloak does not come with any pre-created user, so let’s create our first user, “Oleg” Click on the Users menu on the left and then click the Add User button.

Keycloak — Add User

Oieg will require a password to login to Keycloak. Create a password credential for user your Oleg. Click on the “Credentials” tab and write both password and password confirmation as the password. Turn off the Temporary password switch so we do not need to change the password on the next login. Click “Set Password” to save your password credential. Finally, you need to assign the created PERSON role to Oleg. To do this, click on the Role Mappings tab, select the PERSON role, and click on “add selected”.

3.4 Add a Client

Clients are entities that will request the authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single-sign-on. These clients just want Keycloak to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.

Let’s create a client that we will use to secure our Spring Boot REST service.

Click on the Clients menu on the left and then click on Add Client.

Keycloak — Add Client

In the form, fill Client Id as app, select OpenID Connect for the Client Protocol and click Save. In the client details form, we need to change the Access Type to confidential instead of defaulted public (where client secret is not required). Turn on the “Authorization Enabled” switch before you save the details.

3.5 Request an Access Token

A client requests a security token by making a Token Exchange request to the token endpoint in Keycloak using the HTTP POST method.

Go to http://localhost:8080/auth/realms/automobile/protocol/openid-connect/token

Postman — Token Exchange Request

It is expected to receive a JSON response with an access token and refresh token together with other accompanying details. The received access token can be used in every request to a Keycloak secured resource by simply placing it as a bearer token in the Authorization header:

Postman — Token Exchange Request

or generate new access token and refresh token

Postman — Token Exchange Request

Guide for using endpoints the app:

Go to http://localhost:8088/demo/api/automobiles to test and would specify OAuth 2.0 authorization redirect a username: oleg and password: admin

• GET request to /api/automobiles/ returns a list of "automobiles";
• GET request to /api/automobiles/1 returns the "automobile" with ID 1;
• POST request to /api/automobiles/ with a "automobile" object as JSON creates a new "automobile";
• PUT request to /api/automobiles/3 with a "automobile" object as JSON updates the "automobile" with ID 3;
• DELETE request to /api/automobiles/4 deletes the "automobile" with ID 4;
• DELETE request to /api/automobiles/ deletes all the "automobiles".

---

• GET request to /api/automobiles?color=madeira-violet returns the "automobile"`s with color madeira-violet;
• GET request to /api/automobiles?name=BMW&color=techno-violet returns the "automobile"`s with name BMW and color techno-violet;
• GET request to /api/automobiles?colorStartsWith=Ma&page=0&size=2 returns the "automobile"`s with color which starts with "m". Included Pagination and sorting;

or use Swagger API http://localhost:8088/demo/swagger-ui.html

and generation API docks http://localhost:8088/demo/v3/api-docs.yaml

Appendix B.

• Do not forget, if you see db, open the Windows Services Manager on your Windows 10 computer and stop postgres

4. Docker control commands

• Check all the images you have:

docker images

5. End stop app

• Stop containers:

docker-compose down

• Remove old stopped containers of docker-compose

docker-compose rm -f