Enhance documentation regarding arm/m1 (#2453)

* Update docs to help Apple Mac M1 Users
 * Update missing information about
 * building react app
 * Update prerequisites docs

Co-authored-by: Roman Zabaluev <rzabaluev@provectus.com>

README.md

@@ -137,14 +137,10 @@ Quick-start instruction [here](helm_chart.md)
 
 Check [software-required.md](documentation/project/contributing/software-required.md)
 
-### Building
+### Building and Running
 
 Check [building.md](documentation/project/contributing/building.md)
 
-### Running
-
-Check [running.md](documentation/project/contributing/running.md)
-
 ## Liveliness and readiness probes
 Liveliness and readiness endpoint is at `/actuator/health`.
 Info endpoint (build info) is located at `/actuator/info`.

documentation/project/contributing/README.md

@@ -2,8 +2,7 @@
 
 ### Set up the local environment for development
 
-* [Prerequisites](software-required.md)
+* [Prerequisites](prerequisites.md)
 <!--* [Setting up git](set-up-git.md)-->
 * [Building the app](building.md)
-* [Running the app](running.md)
 * [Writing tests](testing.md)

documentation/project/contributing/building.md

@@ -1,31 +1,70 @@
-### Building the application locally
+# Build & Run
 
-Once you installed the prerequisites and cloned the repository, run the following commands in your project directory:
+Once you installed the prerequisites and cloned the repository, run the following steps in your project directory:
 
-Build a docker container with the app:
+## Step 1 : Build
+> **_NOTE:_**  If you are an macOS M1 User then please keep in mind below things
+
+> Make sure you have ARM supported java installed
+
+> Skip the maven tests as they might not be successful
+
+> Comment out `com.spotify` plugin in `kafka-ui-api` pom file
+
+> Once your build is successful you need to create docker image manually as you'd commented `com.spotify` plugin
+
+> ```docker build --platform linux/arm64 -t provectuslabs/kafka-ui:latest --build-arg JAR_FILE=kafka-ui-api-0.0.1-SNAPSHOT.jar .```
+
+
+- if you need to build the frontend `kafka-ui-react-app`, go here
+     - [kafka-ui-react-app-build-documentation](../../../kafka-ui-react-app/README.md)
+
+- Build a docker image with the app
+```sh
+./mvnw clean install -Pprod
+```
+
+- In case you want to build `kafka-ui-api` by skipping the tests
 ```sh
 ./mvnw clean install -Dmaven.test.skip=true -Pprod
 ``` 
-Start the app with Kafka clusters:
+
+- To build only the `kafka-ui-api` you can use this command:
+```sh
+./mvnw -f kafka-ui-api/pom.xml clean install -Pprod -DskipUIBuild=true
+```
+
+If this step is successful, it should create a docker image named `provectuslabs/kafka-ui` with `latest` tag on your local machine except macOS M1.
+
+## Step 2 : Run
+#### Using Docker Compose
+> **_NOTE:_**  If you are an macOS M1 User then you can use arm64 supported docker compose script `./documentation/compose/kafka-ui-arm64.yaml`
+ - Start the `kafka-ui` app using docker image built in step 1 along with Kafka clusters:
 ```sh
 docker-compose -f ./documentation/compose/kafka-ui.yaml up -d
-``` 
-To see the app, navigate to http://localhost:8080.
+```
 
-If you want to start only kafka clusters (to run the app via `spring-boot:run`):
+#### Using Spring Boot Run
+ - If you want to start only kafka clusters (to run the `kafka-ui` app via `spring-boot:run`):
 ```sh
 docker-compose -f ./documentation/compose/kafka-clusters-only.yaml up -d
 ``` 
+- Then start the app.
+```sh
+./mvnw spring-boot:run -Pprod
 
-Then, start the app.
-
-### Building only the API
+# or
 
-To build only the kafka-ui-api you can use this command:
-```sh
-./mvnw -f kafka-ui-api/pom.xml clean install -Pprod -DskipUIBuild=true
+./mvnw spring-boot:run -Pprod -Dspring.config.location=file:///path/to/conf.yaml
 ```
 
-## Where to go next
-
-In the next section, you'll [learn how to run the application](running.md).
+#### Running in kubernetes
+- Using Helm Charts
+```sh bash
+helm repo add kafka-ui https://provectus.github.io/kafka-ui
+helm install kafka-ui kafka-ui/kafka-ui
+```
+To read more please follow to [chart documentation](../../../charts/kafka-ui/README.md).
+ 
+## Step 4 : Access Kafka-UI
+ - To see the `kafka-ui` app running, navigate to http://localhost:8080.

documentation/project/contributing/prerequisites.md

@@ -0,0 +1,39 @@
+### Prerequisites
+
+This page explains how to get the software you need to use a Linux or macOS
+machine for local development. 
+
+Before you begin contributing you must have:
+
+* A GitHub account
+* `Java` 13 or newer
+* `Git`
+* `Docker`
+
+### Installing prerequisites on macOS
+1. Install [brew](https://brew.sh/).
+2. Install brew cask:
+```sh
+brew cask
+``` 
+3. Install JDK 13 via Homebrew cask:
+```sh
+brew tap adoptopenjdk/openjdk
+brew install adoptopenjdk13
+```
+4. Verify Installation
+```sh
+java -version
+```
+Note : In case JAVA13 is not set as your default Java then you can consider to include JAVA13 in your PATH after installation
+```sh
+export PATH="/Library/Java/JavaVirtualMachines/adoptopenjdk-13.jdk/Contents/Home/bin:$PATH
+```
+## Tips
+
+Consider allocating not less than 4GB of memory for your docker. 
+Otherwise, some apps within a stack (e.g. `kafka-ui.yaml`) might crash.
+
+## Where to go next
+
+In the next section, you'll [learn how to Build and Run kafka-ui](building.md).

documentation/project/contributing/running.md

@@ -1,25 +0,0 @@
-# Running the app
-
-### Running locally via docker
-If you have built a container locally or wish to run a public one you could bring everything up like this:
-```shell
-docker-compose -f documentation/compose/kafka-ui.yaml up -d
-```
-
-### Running locally without docker
-Once you built the app, run the following in `kafka-ui-api/`:
-
-```sh
-./mvnw spring-boot:run -Pprod
-
-# or
-
-./mvnw spring-boot:run -Pprod -Dspring.config.location=file:///path/to/conf.yaml
-```
-
-### Running in kubernetes
-``` bash
-helm repo add kafka-ui https://provectus.github.io/kafka-ui
-helm install kafka-ui kafka-ui/kafka-ui
-```
-To read more please follow to [chart documentation](../../../charts/kafka-ui/README.md)

documentation/project/contributing/software-required.md

@@ -1,31 +0,0 @@
-### Get the required software for Linux or macOS
-
-This page explains how to get the software you need to use a Linux or macOS
-machine for local development. Before you begin contributing you must have:
-
-* a GitHub account
-* Java 13 or newer
-* `git`
-* `docker`
-
-### Installing prerequisites on macOS
-1. Install [brew](https://brew.sh/).
-
-2. Install brew cask:
-```sh
-> brew cask
-``` 
-3Install JDK 13 via Homebrew cask:
-```sh
-> brew tap adoptopenjdk/openjdk
-> brew install adoptopenjdk13
-```
-
-## Tips
-
-Consider allocating not less than 4GB of memory for your docker. 
-Otherwise, some apps within a stack (e.g. `kafka-ui.yaml`) might crash.
-
-## Where to go next
-
-In the next section, you'll [learn how to build the application](building.md).