diff --git a/README.md b/README.md index 6dcb20cd772..332eb1f38e2 100644 --- a/README.md +++ b/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`. diff --git a/documentation/project/contributing/README.md b/documentation/project/contributing/README.md index f30100ecf61..4c88e40c348 100644 --- a/documentation/project/contributing/README.md +++ b/documentation/project/contributing/README.md @@ -2,8 +2,7 @@ ### Set up the local environment for development -* [Prerequisites](software-required.md) +* [Prerequisites](prerequisites.md) * [Building the app](building.md) -* [Running the app](running.md) * [Writing tests](testing.md) \ No newline at end of file diff --git a/documentation/project/contributing/building.md b/documentation/project/contributing/building.md index bb8d7bc2241..25462100e9a 100644 --- a/documentation/project/contributing/building.md +++ b/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). \ No newline at end of file +#### 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. \ No newline at end of file diff --git a/documentation/project/contributing/prerequisites.md b/documentation/project/contributing/prerequisites.md new file mode 100644 index 00000000000..24f032dbab6 --- /dev/null +++ b/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). diff --git a/documentation/project/contributing/running.md b/documentation/project/contributing/running.md deleted file mode 100644 index 6df67370f6f..00000000000 --- a/documentation/project/contributing/running.md +++ /dev/null @@ -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) diff --git a/documentation/project/contributing/software-required.md b/documentation/project/contributing/software-required.md deleted file mode 100644 index 8d3b86c7311..00000000000 --- a/documentation/project/contributing/software-required.md +++ /dev/null @@ -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).