Practicing to build Microservices with Quarkus, Quarkus-extension, Keycloak, and SSL integrated

This project was created to practice building Microservices with Quarkus, Securing services with Keycloak and testing the performance of hibernate-orm and hibernate-reactive. In this project, there is a sample of the Rest-API project that contains many samples of Endpoint classes and samples of hibernate queries, etc. If you are interested, let's see a couple of documentation below.

---

Table of contents

• Introduction
• Prerequisites
• How to Setup ?
  • 1. Clone the Project
  • 2. Localhost Setup
  • 3. Environment Variables Setup
  • 4. Create Local DNS
  • 5. Create certificate for Keycloak and SLL
  • 6. Run Keycloak and PostgreSQL
  • 7. Setup Keycloak
• How to run a service ?
• Postman Collection file
• Architecture Study Case
• Performance Test

---

Introduction

This project is build by Quarkus, you can see what is Quarkus on their official website. Goals of this project is "to learn and find a better way how to build a Microservices System Architecture using Quarkus", so the description on the README.md file will be changed periodically following updates of this project.
There are some important things you should know about this project

1. Root Folder description
   • dependencies contains a couple of "Quarkus-extensions" and dependency projects will be used on each service.
   • docker contains files that needed to build Container of Keycloak and PostgresQL
   • docs contains image assets and markdown (.md) files of project documentation
   • microservices is a parent project of all Micro-service project,
   • nginx contains files that needed to run the Nginx
2. Incomplete parts
   1. microservices/rest-sample is not completed because need to add some more sample there.
   2. microservices/rest-sample-reactive is totally not created yet, this is same like Rest Sample but using Reactive approach
   3. Performance test with JMeter is totally not created yet. This part will test some API endpoint from Rest Sample and Rest-Sample Reactive services to compare their performance
   4. Real microservices sample, it will consist of several examples of backend services needed to build an e-commerce application This part will use Kafka for message broker.
   5. Documentation of the Architecture
3. This project is developed and tested on MacOS, it might not be working properly on Windows OS

---

Prerequisites

To follow this guide, you need:

1. Understand Java
2. Understand Object Oriented Programming
3. Understand Docker
4. GraalVM 21+ (Community Edition / Oracle) installed
5. Apache Maven 3.9.6 or newer
6. Docker

⚠️ It would be better you install sdkman on your computer, and then use sdkman to install GraalVM
See this to install SDKMAN

---

How to setup ?

Please follow these steps to run this project correctly

1. Clone the project

There is no special way to clone this project

2. Localhost setup

We need to setup our localhost or our Local Machine to make a DNS running on our Local Machine

- Linux / MacOS

1. Open your terminal
2. Type sudo vi /etc/hosts and input your computer password
3. Press i on keyboard and type this on new line

   ...
   
   10.123.123.123 <domain name that you want>
   10.123.123.123 keycloak.<domain name that you want>

   it would be like

   ...
   
   10.123.123.123 example.com 
   10.123.123.123 keycloak.example.com 

   or

   ...
   
   10.123.123.123 practicing-quarkus.com
   10.123.123.123 keycloak.practicing-quarkus.com 

   or something else
4. Press Esc on keyboard, then press Shift + Z twice

- Windows

• Coming soon

3. Environment Variables Setup

1. Please copy docker_env.env.example to docker_env.env
2. Fill in these variable first
   • SERVER_HOST is the domain name that you have added before to /etc/hosts
   • KEYCLOAK_HOST is your domain name with prefix keycoak.
   • All environment variables with prefix DATABASE_
   • KEYCLOAK_EXTERNAL_PORT is accessible port of keycloak container
   • KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD is a user credential will be used to sign in to keycloak admin console
   • KEYCLOAK_KEYSTORE_PASSWORD keystore password to secure the keycloak

4. Create local DNS

This step is to make our domain works on our local

1. Open your terminal
2. Navigate to this project root folder
3. Type ./create-local-dns.sh and enter
4. The result would be like this
   
5. To make sure your domain works, type this on terminal,

   ping 10.123.123.123

   and

   ping <your domain>

   if it works, the result would be like this

   PING q-learning.com (10.123.123.123): 56 data bytes
   64 bytes from 10.123.123.123: icmp_seq=0 ttl=64 time=0.118 ms
   64 bytes from 10.123.123.123: icmp_seq=1 ttl=64 time=0.299 ms
   64 bytes from 10.123.123.123: icmp_seq=2 ttl=64 time=0.296 ms
   64 bytes from 10.123.123.123: icmp_seq=3 ttl=64 time=0.220 ms
   

5. Create certificate for keycloak and SSL

Certificate is needed to secure our keycloak

1. Run ./create-certificate.sh on your terminal
2. After that check on folder ./nginx/certs, self-signed.crt and self-signed.key files would be there
   
3. And then check on folder ./docker/keycloak/, server.keystore would be there
   (don't worry about Dockerfile, it would be generated letter)

6. Run Keycloak and PostgreSQL

1. On your terminal, please run this ./compose-up-keycloak-posgress.sh
2. Please wait until finish, the result would be like this

7. Setup keycloak

Click the title to see the complete instruction

8. Complete

Now, our setup to run this project is complete, so you can run Rest Sample project by open the terminal and enter to microservices/rest-sample folder and then run ./run-debug.sh script