How to run Matcha 🍃
The project need to run with Keycloak and Swagger, so I recommend to setup and run with Docker container, if you already setup Keycloak and Swagger inside your local machine, you can skip this step.
You need to setup environment to run Docker, so there are many different ways to do it, depends on your OS, so I just show some ways here.
Docker Desktop is good for any OS, like Window or MacOS, so just go to the Docker website to download and install it.
You can download Docker in the original link: https://www.docker.com/products/docker-desktop/
Install it and open Docker Desktop, register and login to your account.
I use MacOS, so this is the Docker Desktop
Rancher Desktop is also a version which supported Docker, Rancher Desktop does not have many functions like Docker Desktop, some features are still in experimental state. But if you want to try it, you can download it in Rancher website: https://rancherdesktop.io/
My company is not allow me to use the Docker Desktop, so Rancher is another choice, not too good, but still ok. This is the Rancher Desktop screen:
If you are using Ubuntu/Linux OS, you can setup WSL and config it to run Docker, I will not cover this here because it has a bit complicate, you can setup it by yourself with some research on the Internet.
Now, go to the next step.
Before run the project, we need to setup the .env file, you can create a new .env inside project root folder, and setup your configurations, also your credentials. .env is already declare in the .gitignore, so that file will be not push to Github. We do this for security purpose.
I already created a .env.sample inside project root folder, so you can use that structure, copy all the needed variable to your new .env file, then add yours configuration.
And example .env file:
# Postgres
POSTGRES_USER=admin
POSTGRES_PASSWORD=admin
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
SERVER_PORT=80
# Swagger UI
URLS=[{ url: 'http://localhost:8081/product/v3/api-docs', name: 'Product'}]
# Start all service when run docker compose up
COMPOSE_FILE=docker-compose.yml
# ********************* #
# SERVICES
# ********************* #
# Product
PRODUCT_DATASOURCE_URL=jdbc:postgresql://localhost:5432/postgres
PRODUCT_DATA_USERNAME=postgres
PRODUCT_DATA_PASSWORD=123456
Ok, so the setup is almost done, ready to run the Matcha 🍃
The project already has Keycloak and Swagger container setup in the docker-compose.yml, so you can open project with your IDE and run the docker-compose.yml first
I use IntelliJ here:
You open Terminal/Command Prompt inside the project folder which is depend on your OS, then run docker compose up to run the container
Then waiting for download the Keycloak, Swagger images and start the containers. This is the screen after container run successfully:
Now, you can go to the sell-bff module, then run SellBffApplication
Ok, now we almost done here, now you can run the service you want to run, I run product here for example:
Now you can open your browser: Microsoft Edges, Google Chrome,... and go to the link:
http://localhost:8090/swagger-ui/
You can see the Swagger UI, with module Product on the top right corner
I already wrote an API POST Product here, so you can see it in the Swagger UI, if you have many different APIs here, you will be able to see them all.
- To test the API, you click on the button
Authorize
Then, Authorize again, it will redirect you to another page to login, you can login with
username: admin
password: password
The screen show you are logged in:
Ok, press close, and now everything is running, and you can test your API endpoint like using Postman,...
Hopefully, these documents will help you when running this project. Microservices systems are often complex and costly, and at times, you may feel overwhelmed, wondering, "Why do I need to run so many services just for a small feature?" However, this approach provides us with a wealth of new knowledge and valuable experience. Enjoy the journey! 🍃