From 34d7c2a8b26625461ee7fc56f6d1ae5d9a433f0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fernandes?= Date: Wed, 3 Jul 2024 15:22:53 +0200 Subject: [PATCH 1/5] chore: enhance local setup process and local install documentation --- docs/Local Development Install.md | 77 ++++++++++++++++++++----------- local-setup.sh | 61 ++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 27 deletions(-) create mode 100755 local-setup.sh diff --git a/docs/Local Development Install.md b/docs/Local Development Install.md index cb0cadd3..073ad0d8 100644 --- a/docs/Local Development Install.md +++ b/docs/Local Development Install.md @@ -83,34 +83,57 @@ Let's begin local development install! ![Docker Desktop](images/dev/3.png "Docker install") -- ### Running containers - This project includes integrated support for Spring Boot Docker Compose, facilitating the setup of Keycloak and PostgreSQL without manual intervention. - - You won't need to manually start containers or configure settings. The application will reference the `compose.yaml` file located at the root of the project. - - Feel free to adjust configurations (such as ports and credentials) in the `compose.yaml` file to suit your requirements. - - When the application starts, it automatically creates a PostgreSQL container with the provided environment credentials. Additionally, a new database for Keycloak is set up. - - On startup, the application also creates a Keycloak container based on the configurations in the Compose file. Initial configurations, including the creation of realms, clients, and users, are performed using the `dcm_realm.json` file. - - ![Docker desktop running containers](images/dev/11.png) - - Further you can login with keycloak admin credentials configured in `compose.yaml` and modify users to you heart's content(under the users tabs, credentials for them, assing roles, etc) - - Ref: https://spring.io/blog/2023/06/21/docker-compose-support-in-spring-boot-3-1 +- ### Running environment locally +There is a script called `local-setup.sh` located in the project root directory. +If you use a UNIX based system, you can simply run the script by executing the following commands: + +```sh +chmod +x local-setup.sh +source local-setup.sh +``` + +The execution will: + +1 - Clean and Install maven dependencies +```sh +mvn clean install +``` +2 - Assign execution permissions to `create_keycloak_db.sh` +```sh +chmod +x ./dev/create_keycloak_db.sh +``` +3 - Start docker containers for postgres and keycloak +```sh +docker compose up -d +``` +4 - Install frontend dependencies +```sh +npm install --force --legacy-peer-deps +``` +5 - Configure local environment variable pertaining the client secret for application.yaml (keycloak > clientSecret) + +6 - Start the backend application +```sh +java -jar demand-capacity-mgmt-backend/target/demand-capacity-mgmt-backend-0.0.1-SNAPSHOT.jar +``` + +Alternatively, you can follow all the above steps in sequence. + +> On step 3, the execution creates a Keycloak container based on the configurations in the compose.yaml file. Initial configurations, including the creation of realms, clients, and users, are performed using the `dcm_realm.json` file. + +> For step 5, navigate to dcmauth client on keycloak panel and copy the client secret under credentials. + open your application.yaml and place it on the dcmsecr section. After that run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! + + You can access keycload on `http://localhost:28080/` and login with keycloak admin credentials configured in `compose.yaml` and modify users to you heart's content (under the users tabs, credentials for them, assing roles, etc) **Remember you need to have a user role on all users, it can be ADMIN, CUSTOMER, SUPPLIER** failing to have one of these roles won't let the user login in the app. - [Download keycloak realm json](realm-export.json) - - ### Fetching the keycloak client credential - before booting the project again navigate to dcmauth client on keycloak panel and copy the client secret under credentials. - open your application.yaml and place it on the dcmsecr section. - - after that run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! + After that run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! + + [Download keycloak realm json](realm-export.json) ![Postman](images/dev/6.png "Postman login") @@ -133,15 +156,15 @@ Let's begin local development install! - ### Run the front-end - when postman is working, you need to open the front end on your IDE of choice and run on a terminal inside the front-end folder, make sure you have NodeJS installed on your machine. - - npm install --force --legacy-peer-deps + After executing `local-setup.sh` script, all frontend dependencies should be already installed. Now, you can run: - npm start + ```sh + npm start + ``` the app will be booted on localhost:3000 - for a user to correctly login you need to add a company to the DB and add that company to the user + > For a user to correctly login you need to add a company to the DB and add that company to the user Admin needs to have a company, even if a dummy one. otherwise you will get lowerCase error on frontend when trying to read company Ids diff --git a/local-setup.sh b/local-setup.sh new file mode 100755 index 00000000..0c8fd118 --- /dev/null +++ b/local-setup.sh @@ -0,0 +1,61 @@ +#!/bin/bash + +# Function to kill any process running on port 8080 +kill_existing_java_process() { + local PID + PID=$(lsof -t -i:8080) + if [ -n "$PID" ]; then + echo "Killing existing process on port 8080 (PID: $PID)..." + kill -9 $PID + sleep 5 + else + echo "No existing process running on port 8080." + fi +} + +maven_clean_install() { + echo "Cleaning and installing Maven dependencies..." + mvn clean install +} + +set_executable_permissions() { + echo "Setting executable permissions for create_keycloak_db.sh..." + chmod +x ./dev/create_keycloak_db.sh +} + +start_docker_containers() { + echo "Starting Docker containers..." + docker compose up -d + echo "Waiting for containers to be fully up..." + sleep 5 +} + +install_frontend_dependencies() { + echo "Installing frontend dependencies..." + cd demand-capacity-mgmt-frontend || handle_error "Failed to change directory to demand-capacity-mgmt-frontend" + npm install --force --legacy-peer-deps + cd .. +} + +config_client_secret() { + export DCMSECR=99efa50e0cde9e3b1f693e75d5623059e911ab6b26050192543cbf4cd19bc2d8 +} + +start_backend() { + echo "Starting backend and running migrations..." + java -jar demand-capacity-mgmt-backend/target/demand-capacity-mgmt-backend-0.0.1-SNAPSHOT.jar +} + +main() { + check_docker_running + kill_existing_java_process + maven_clean_install + set_executable_permissions + start_docker_containers + install_frontend_dependencies + config_client_secret + start_backend +} + +# LOCAL SETUP EXECUTION +main From 6f38300d708fa116b6f34e048d4fcdb46faffd1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fernandes?= Date: Wed, 3 Jul 2024 15:44:42 +0200 Subject: [PATCH 2/5] chore: enhanced local install docs --- docs/Local Development Install.md | 52 +++++++++++++++---------------- local-setup.sh | 2 +- 2 files changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/Local Development Install.md b/docs/Local Development Install.md index 073ad0d8..327ad31a 100644 --- a/docs/Local Development Install.md +++ b/docs/Local Development Install.md @@ -84,7 +84,7 @@ Let's begin local development install! ![Docker Desktop](images/dev/3.png "Docker install") -- ### Running environment locally +### Backend environment setup There is a script called `local-setup.sh` located in the project root directory. If you use a UNIX based system, you can simply run the script by executing the following commands: @@ -107,37 +107,49 @@ chmod +x ./dev/create_keycloak_db.sh ```sh docker compose up -d ``` +> On this step, the execution creates a Keycloak container based on the configurations in the compose.yaml file. Initial configurations, including the creation of realms, clients, and users, are performed using the `dcm_realm.json` file. + [Download keycloak realm json](realm-export.json) + 4 - Install frontend dependencies ```sh +cd demand-capacity-mgmt-frontend npm install --force --legacy-peer-deps ``` -5 - Configure local environment variable pertaining the client secret for application.yaml (keycloak > clientSecret) +5 - Automatically configures local environment variable pertaining the client secret for application.yaml (keycloak > clientSecret) + +> For manual setup, navigate to dcmauth client on keycloak panel and copy the client secret under credentials. + Open your application.yaml and place it on the dcmsecr section. After that, run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! 6 - Start the backend application ```sh java -jar demand-capacity-mgmt-backend/target/demand-capacity-mgmt-backend-0.0.1-SNAPSHOT.jar ``` -Alternatively, you can follow all the above steps in sequence. - -> On step 3, the execution creates a Keycloak container based on the configurations in the compose.yaml file. Initial configurations, including the creation of realms, clients, and users, are performed using the `dcm_realm.json` file. +**Alternatively, you can manually follow all the above steps in sequence.** -> For step 5, navigate to dcmauth client on keycloak panel and copy the client secret under credentials. - open your application.yaml and place it on the dcmsecr section. After that run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! - - You can access keycload on `http://localhost:28080/` and login with keycloak admin credentials configured in `compose.yaml` and modify users to you heart's content (under the users tabs, credentials for them, assing roles, etc) + You can access keycloak on `http://localhost:28080/` and login with admin credentials configured in `compose.yaml` and modify users to you heart's content (under the users tabs, credentials for them, assing roles, etc) **Remember you need to have a user role on all users, it can be ADMIN, CUSTOMER, SUPPLIER** failing to have one of these roles won't let the user login in the app. -- ### Fetching the keycloak client credential - After that run the project and in postman you should be able to login on the token endpoint with the credentials you modified on keycloak! + ### Frontend environment setup + If you have run step 4 from [Backend environment setup](#backend-environment-setup), then frontend dependencies should be already installed. Now, you can run: - [Download keycloak realm json](realm-export.json) + ```sh + npm start + ``` + + the app will be booted on localhost:3000 + + > For a user to correctly login you need to add a company to the DB and add that company to the user + Admin needs to have a company, even if a dummy one. + otherwise you will get lowerCase error on frontend when trying to read company Ids + +### Configure postman collection requests! + Now, using postman, you should be able to login on the token endpoint with the credentials you modified on keycloak! ![Postman](images/dev/6.png "Postman login") -- ### Configure postman collection requests! for the other requests on postman you need to alter the authorization tab. check the config on the images provided. @@ -153,20 +165,6 @@ Alternatively, you can follow all the above steps in sequence. ![Postman](images/dev/10.png "Postman config") - - -- ### Run the front-end - After executing `local-setup.sh` script, all frontend dependencies should be already installed. Now, you can run: - - ```sh - npm start - ``` - - the app will be booted on localhost:3000 - - > For a user to correctly login you need to add a company to the DB and add that company to the user - Admin needs to have a company, even if a dummy one. - otherwise you will get lowerCase error on frontend when trying to read company Ids ## Postman Collection diff --git a/local-setup.sh b/local-setup.sh index 0c8fd118..9ad07da6 100755 --- a/local-setup.sh +++ b/local-setup.sh @@ -32,7 +32,7 @@ start_docker_containers() { install_frontend_dependencies() { echo "Installing frontend dependencies..." - cd demand-capacity-mgmt-frontend || handle_error "Failed to change directory to demand-capacity-mgmt-frontend" + cd demand-capacity-mgmt-frontend npm install --force --legacy-peer-deps cd .. } From 7fe45ece4916ffd8e7b7c0d6063d1b3766d41dea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fernandes?= Date: Thu, 4 Jul 2024 09:44:44 +0200 Subject: [PATCH 3/5] chore: add copyright and licence header --- local-setup.sh | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/local-setup.sh b/local-setup.sh index 9ad07da6..ff40cecd 100755 --- a/local-setup.sh +++ b/local-setup.sh @@ -1,3 +1,22 @@ +# ******************************************************************************* +# Copyright (c) 2024 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License, Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0. +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************** + #!/bin/bash # Function to kill any process running on port 8080 From 857cabf607c74328efee1122db5425ebc139bdc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fernandes?= Date: Thu, 4 Jul 2024 10:59:20 +0200 Subject: [PATCH 4/5] chore: removed force on frontend dependency install --- local-setup.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/local-setup.sh b/local-setup.sh index ff40cecd..e699c639 100755 --- a/local-setup.sh +++ b/local-setup.sh @@ -20,7 +20,7 @@ #!/bin/bash # Function to kill any process running on port 8080 -kill_existing_java_process() { +kill_existing_process() { local PID PID=$(lsof -t -i:8080) if [ -n "$PID" ]; then @@ -52,7 +52,7 @@ start_docker_containers() { install_frontend_dependencies() { echo "Installing frontend dependencies..." cd demand-capacity-mgmt-frontend - npm install --force --legacy-peer-deps + npm install --legacy-peer-deps cd .. } @@ -67,7 +67,7 @@ start_backend() { main() { check_docker_running - kill_existing_java_process + kill_existing_process maven_clean_install set_executable_permissions start_docker_containers From 2db7f2b2621b24b0f5e638c18ff2e3899b3bb818 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Fernandes?= Date: Fri, 5 Jul 2024 13:05:03 +0200 Subject: [PATCH 5/5] chore: removed extra funtion call in local setup script and enhanced local dev docs --- docs/Local Development Install.md | 7 +++++++ local-setup.sh | 1 - 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/Local Development Install.md b/docs/Local Development Install.md index 327ad31a..bd1f8c62 100644 --- a/docs/Local Development Install.md +++ b/docs/Local Development Install.md @@ -145,6 +145,13 @@ java -jar demand-capacity-mgmt-backend/target/demand-capacity-mgmt-backend-0.0.1 Admin needs to have a company, even if a dummy one. otherwise you will get lowerCase error on frontend when trying to read company Ids + Existing migrations will add 3 users in the database (with corresponding roles and authorizations already configured on keycload DCM real) which you can use in your local setup: + + - username: dcm_admin; password: test + - username: customer; password: test + - username: supplier; password: test + + ### Configure postman collection requests! Now, using postman, you should be able to login on the token endpoint with the credentials you modified on keycloak! diff --git a/local-setup.sh b/local-setup.sh index e699c639..770a68d1 100755 --- a/local-setup.sh +++ b/local-setup.sh @@ -66,7 +66,6 @@ start_backend() { } main() { - check_docker_running kill_existing_process maven_clean_install set_executable_permissions