diff --git a/docs/Local Development Install.md b/docs/Local Development Install.md index cb0cadd3..bd1f8c62 100644 --- a/docs/Local Development Install.md +++ b/docs/Local Development Install.md @@ -83,38 +83,80 @@ 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. +### 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: + +```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 +``` +> 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 - 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 manually follow all the above steps in sequence.** + + 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) - 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. + **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. - When the application starts, it automatically creates a PostgreSQL container with the provided environment credentials. Additionally, a new database for Keycloak is set up. + ### 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: - 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. + ```sh + npm start + ``` - ![Docker desktop running containers](images/dev/11.png) + the app will be booted on localhost:3000 - 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) + > 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 - Ref: https://spring.io/blog/2023/06/21/docker-compose-support-in-spring-boot-3-1 + 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: - **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. + - username: dcm_admin; password: test + - username: customer; password: test + - username: supplier; password: test - [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! +### 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. @@ -130,20 +172,6 @@ Let's begin local development install! ![Postman](images/dev/10.png "Postman config") - - -- ### 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 - - 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 new file mode 100755 index 00000000..770a68d1 --- /dev/null +++ b/local-setup.sh @@ -0,0 +1,79 @@ +# ******************************************************************************* +# 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 +kill_existing_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 + npm install --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() { + kill_existing_process + maven_clean_install + set_executable_permissions + start_docker_containers + install_frontend_dependencies + config_client_secret + start_backend +} + +# LOCAL SETUP EXECUTION +main