-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
13 changed files
with
284 additions
and
244 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
27 changes: 27 additions & 0 deletions
27
apps/react/docs/docs/01-Introduction/03-multi-tenancy-concept.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| --- | ||
| id: multi-tenancy-concept | ||
| title: Multi-tenancy Concept | ||
| --- | ||
|
|
||
| # Multi-tenancy Concept | ||
|
|
||
| ## 🌟 Overview | ||
|
|
||
| Multi-tenancy on the WKS Power Platform is designed to provide each tenant with a secure and isolated operational environment, akin to providing separate office suites within a single corporate building. This architecture allows service providers to manage multiple clients efficiently while ensuring that each client's data and operations remain private and secure. | ||
|
|
||
| ## 🏛️ Architectural Overview | ||
|
|
||
| ### Tenant URL Structure 🌐 | ||
|
|
||
| - Each tenant accesses their environment through a unique subdomain, following the format tenant_id.somedomain.com (e.g., saasCustomer1.wksplatform.com). | ||
| - This subdomain serves as the dedicated entry point to the tenant’s specific portion of the platform, ensuring direct and secure access. | ||
|
|
||
| ### Keycloak Realms 🔐 | ||
|
|
||
| - Each tenant has a separate Keycloak realm, providing a dedicated security domain that controls authentication and authorization. This setup ensures that user credentials and permissions are managed locally within each tenant's realm, enhancing security and privacy. | ||
| - Upon onboarding a new tenant, a realm is specifically created and configured with unique security settings and user management protocols tailored to meet the tenant's needs. | ||
|
|
||
| ### MongoDB Databases 🗃️ | ||
|
|
||
| - Each tenant has a separate database to store tenant-specific data securely and maintain complete data isolation between tenants. | ||
| - Creating a dedicated MongoDB database for each new tenant setup, ensuring that data from one tenant is completely inaccessible to another. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
45 changes: 45 additions & 0 deletions
45
apps/react/docs/docs/02-Installation/01-Option 1 Pre-built Docker Images/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| --- | ||
| id: installation-option-1 | ||
| title: Option 1 - Pre-built Docker Images | ||
| --- | ||
|
|
||
| # WKS Platform Installation Guide | ||
|
|
||
| ## Option 1: Running with Pre-built Docker Images | ||
|
|
||
| :::warning | ||
| **⚠️ For Development/Test Environments Only ⚠️**<br /> | ||
| The provided docker-compose files are recommended only for use in development or test environments. | ||
| ::: | ||
|
|
||
| To quickly set up and run the project in a development environment, you can use pre-built Docker images. This approach ensures that all necessary dependencies and services are configured automatically, providing a seamless and consistent environment. | ||
|
|
||
| ```bash | ||
| git clone https://github.com/wkspower/wks-platform-docker.git | ||
| cd wks-platform-docker | ||
| docker-compose up -d | ||
| ``` | ||
|
|
||
| After successfully running `docker-compose up` to start the Docker Compose configuration, it may take a while for all the web applications to finish their startup process. Once the startup is complete, you can access the following web applications: | ||
|
|
||
| - **WKS Platform Portal**: You can access the WKS Platform Portal by opening your web browser and navigating to [http://localhost:3001](http://localhost:3001). Use the following credentials to log in: | ||
| - Username: demo | ||
| - Password: demo | ||
|
|
||
| - **Camunda**: To access the Camunda web application, open your web browser and visit [http://localhost:8080](http://localhost:8080). Use the following credentials to log in: | ||
| - Username: demo | ||
| - Password: demo | ||
|
|
||
| - **Keycloak**: Access the Keycloak web application by opening your web browser and visiting [http://localhost:8082](http://localhost:8082). Use the following credentials to log in as an administrator: | ||
| - Username: admin | ||
| - Password: admin | ||
|
|
||
| - **MinIO**: Access the MinIO web application by opening your web browser and visiting [http://localhost:9000](http://localhost:9000). Use the following credentials to log in as an administrator: | ||
| - Username: minio | ||
| - Password: #minio00# | ||
|
|
||
| Please note that it may take some time for the web applications to become fully operational, especially if this is the first time you are running them. If you encounter any issues, wait a few moments and try accessing the applications again. | ||
|
|
||
| Additionally, the MongoDB database used by these applications is running on port 27017. | ||
|
|
||
| Remember to ensure that you have Docker installed on your system before running the `docker-compose up` command. |
30 changes: 30 additions & 0 deletions
30
...llation/02-Option 2 Local Development Setup/01-docker-compose-filesoverview.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| --- | ||
| id: docker-compose files overview | ||
| title: 📦 Docker-Compose Files | ||
| --- | ||
|
|
||
| # Docker-Compose Files Overview 📦 | ||
|
|
||
| ## 🏗️ Core Components | ||
| - `docker-compose.yaml`: Sets up essential services like Minio, MongoDB, OPA, Keycloak, and Storage-API. | ||
| - `docker-compose.camunda[CAMUNDA_VERSION].yaml`: Incorporates Camunda servers with key backend components such as the REST-API and [External Tasks](https://docs.camunda.org/manual/7.21/user-guide/process-engine/external-tasks/). | ||
| - `docker-compose.demo-data-loader.[CAMUNDA_VERSION].yaml`: Automates the loading of demo data into the platform | ||
| - [Demo Case Definitions, Forms and Processes](https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/demo-data-loader/data) into Camunda and MongoDB | ||
| - [Realms, Groups and Users](https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/demo-data-loader/src/main/resources) into Keycloak. | ||
| - `docker-compose.event-hub.[CAMUNDA_VERSION].yaml`: Optional but necessary for integrating [System Notifications](https://docs.wkspower.com/docs/System%20Notifications/) and/or [websockets for the case-portal](https://github.com/wkspower/wks-platform/issues/246). | ||
| - Customizes Camunda with a plugin sending Kafka messages for registered events. | ||
| - Starts Kafka and Zookeeper. | ||
| - Enables Kafka communication from [External Tasks](https://docs.camunda.org/manual/7.21/user-guide/process-engine/external-tasks/). | ||
|
|
||
| ## 🛠️ Additional Components | ||
| - `docker-compose.websocket.yaml`: Enables real-time communication for the case-portal. See [websockets for the case-portal](https://github.com/wkspower/wks-platform/issues/246). | ||
| - `docker-compose.novu.yaml`: Manages notification dispatch using [novu-publisher](https://docs.wkspower.com/docs/System%20Notifications/). | ||
| - `docker-compose.email-sender.yaml`: Handles outgoing [email communications](https://www.wkspower.com/blog/presenting-email-to-case/). | ||
| - `docker-compose.portal.yaml`: Deploys the front-end React case-portal. | ||
|
|
||
| ## 🖥️ Shell Scripts for Local Development | ||
|
|
||
| For ease of local development, various shell scripts are available: | ||
| - **Server Management:** `docker-servers-[startup/shutdown].sh` for managing all servers using Docker, ideal for UI development. | ||
| - **Portal Management:** `docker-portal-[startup/shutdown].sh` focuses on backend development needs. | ||
| - **Full Startup Scripts:** `docker-full-startup.sh` for comprehensive loading of all components, available for Camunda 7 and 8, facilitating quick testing and demos. |
16 changes: 16 additions & 0 deletions
16
...on/02-Option 2 Local Development Setup/02-customizing-environment-variables.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| id: customizing-environment-variables | ||
| title: 📋 Customizing Environment Variables | ||
| --- | ||
|
|
||
| # Customizing Environment Variables 📋 | ||
|
|
||
| - ## For Java Applications ♨️ | ||
| - **Build-Time Configuration:** Environment variables for Java applications are typically defined in `application.yml` files located at the root of each Java project (e.g., the REST-API). | ||
| - **Docker Compose Overrides:** These variables can be overridden at application startup through command line arguments or through Docker Compose configurations. For example, `CAMUNDA_BASE_URL` might be set in the `application.yml`, but it can be overridden by Docker environment settings to suit different deployment environments. | ||
| - ## For React Case-Portal ⚛️ | ||
| - **Build-Time Configuration:** Environment variables for the React Case-Portal are set during the build phase. These are defined in a `.env` file, which must be prepared before building the application. | ||
| - **Docker Compose Overrides:** When deploying with Docker, the environment variables set in the React project's `.env` file can be overridden by those specified in the `docker-compose` files. This is critical when settings need to be adjusted post-deployment without rebuilding the app. | ||
| - ## For Node Applications 🌐 | ||
| - **Build-Time Configuration:** Node applications, such as the mail-sender, use `.env` files for environment configuration. These are crucial for running the applications in different environments, whether locally with Yarn or in Dockerized environments. | ||
| - **Docker Compose Overrides:** In Docker environments, the settings in `.env-sample` are overridden by those specified in the `docker-compose.yml` files. This allows for easy customization of environment variables without modifying the application's code. |
75 changes: 75 additions & 0 deletions
75
...s/02-Installation/02-Option 2 Local Development Setup/03-step-by-step-setup.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| --- | ||
| id: step-by-step-setup | ||
| title: 🛠️ Step by step for local development setup | ||
| --- | ||
|
|
||
| # Step by step for local development setup 🛠️ | ||
|
|
||
| This section will involves several key steps to ensure all components of the WKS Power Platform are properly set up and integrated: | ||
|
|
||
| ## 📋 Prerequisites | ||
| - Docker and Docker Compose are installed on your system. | ||
| - Java 17 and Maven 3.8.x or higher are installed for building the Spring Boot microservices. | ||
| - Node.js, npm, and Yarn are installed for building and running the Node.js React apps. | ||
|
|
||
| ## Step 1: Preparation | ||
|
|
||
| ### I. Clone the WKS Platform repository 📥 | ||
| ```bash | ||
| git clone https://github.com/wkspower/wks-platform.git | ||
| cd wks-platform | ||
| ``` | ||
| ### II. From the project root folder, navigate to the java project folder 🚶♂️ | ||
| ```bash | ||
| cd apps/java | ||
| ``` | ||
| ### III. Build all the microservices at once using Maven for later usage 🏗️ | ||
| ```bash | ||
| mvn clean install package | ||
| ``` | ||
|
|
||
| ## Step 2: Custom Domain Configuration | ||
| :::note | ||
| Skip if you only intent to only use it on localhost | ||
| ::: | ||
|
|
||
| - Copy settings from `/.env-sample` to `/.env` then updated the file to configure essential service URLs, Keycloak Realms, and operational flags: | ||
| - `MONGO_DEMO_DATA_LOADER_DATABASE=subdomain` | ||
| - `KEYCLOAK_TOKEN_URL=http://keycloak:8080/realms/subdomain/protocol/openid-connect/token` | ||
| - `WEBSOCKET_ENABLED=true` | ||
| - `WEBSOCKET_URL=ws://subdomain.domain.io:8484/` | ||
| - Optional for novu notifications: | ||
| - `NOVU_ENABLED=true` | ||
| - `NOVU_PUBLISHER_API_URL=http://subdomain.domain.io:3002/` | ||
| - `NOVU_APP_ID=your-id` | ||
| - `NOVU_API_KEY=your-key` | ||
| - Default Usernames & Passwords also can be changed: | ||
| - `KEYCLOAK_ADMIN=admin` | ||
| - `KEYCLOAK_ADMIN_PASSWORD=admin` | ||
| - `KEYCLOAK_DEFAULT_USER=demo` | ||
| - `KEYCLOAK_DEFAULT_USER_PASSWORD=demo` | ||
| - `KEYCLOAK_DEFAULT_USER_FIRST_NAME=demo` | ||
| - `KEYCLOAK_DEFAULT_USER_LAST_NAME=demo` | ||
| - `[email protected]` | ||
| - `MINIO_ROOT_USER=minio` | ||
| - `MINIO_ROOT_PASSWORD='#minio00#'` | ||
|
|
||
| - Update `docker-compose.portal.yaml:` to ensure front-end configuration aligns with backend services: | ||
| - `REACT_APP_KEYCLOAK_URL=http://subdomain.domain.io:8082/` | ||
| - `REACT_APP_API_URL=http://subdomain.domain.io:8081/` | ||
| - `REACT_APP_STORAGE_URL=http://subdomain.domain.io:8085/` | ||
|
|
||
| ## Step 3: Deployment | ||
|
|
||
| ### 🚀 Run Full Startup Shell Script | ||
| ```bash | ||
| sh docker-full-startup.sh | ||
| ``` | ||
| After successfully running the shell script to start all of the the Docker Compose configurations, it may take a while for all the web applications to finish their startup process. | ||
|
|
||
| ## Step 4: Service Configuration | ||
| :::note | ||
| Skip if application domain havn't been customized | ||
| ::: | ||
|
|
||
| Once the startup is complete, Manually replace wks-portal Keycloak Client's `Web origins` and `Valid redirect URIs` to match your domain. |
36 changes: 36 additions & 0 deletions
36
...cs/02-Installation/02-Option 2 Local Development Setup/04-post-installation.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| id: post-installation | ||
| title: 🎯 Post-Installation | ||
| --- | ||
|
|
||
| # Post-Installation 🎯 | ||
|
|
||
| Once the installation is complete, should be able to access the following web applications: | ||
|
|
||
| - **WKS Platform Portal**: You can access the WKS Platform Portal by opening your web browser and navigating to [http://subdomain.domain.io:3001](http://subdomain.domain.io:3001). Use the following credentials to log in: | ||
| ```bash | ||
| Username: demo | ||
| Password: demo | ||
| ``` | ||
|
|
||
| - **Camunda**: To access the Camunda web application, open your web browser and visit [http://subdomain.domain.io:8080](http://subdomain.domain.io:8080). Use the following credentials to log in: | ||
| ```bash | ||
| Username: demo | ||
| Password: demo | ||
| ``` | ||
|
|
||
| - **Keycloak**: Access the Keycloak web application by opening your web browser and visiting [http://subdomain.domain.io:8082](http://subdomain.domain.io:8082). Use the following credentials to log in as an administrator: | ||
| ```bash | ||
| Username: admin | ||
| Password: admin | ||
| ``` | ||
|
|
||
| - **MinIO**: Access the MinIO web application by opening your web browser and visiting [http://subdomain.domain.io:9000](http://subdomain.domain.io:9000). Use the following credentials to log in as an administrator: | ||
| ```bash | ||
| Username: minio | ||
| Password: #minio00# | ||
| ``` | ||
|
|
||
| Please note that it may take some time for the web applications to become fully operational, especially if this is the first time you are running them. If you encounter any issues, wait a few moments and try accessing the applications again. | ||
|
|
||
| Additionally, the MongoDB database used by these applications is running on port 27017. |
Oops, something went wrong.