|
| 1 | +--- |
| 2 | +htmlid: deploy |
| 3 | +tab_title: Deployment |
| 4 | +--- |
| 5 | +Kroxylicious is a Java application based on [Netty](https://netty.io/), which means it will run anywhere you can run a JVM. (That's a lot of places!) |
| 6 | +To help you get started with Kroxylicious, we've created this quick setup guide. |
| 7 | + |
| 8 | +<br /> |
| 9 | + |
| 10 | +# Getting started |
| 11 | + |
| 12 | +### Prerequisites |
| 13 | + |
| 14 | +#### Java |
| 15 | + |
| 16 | +To get started deploying Kroxylicious, you will need to install a Java Runtime Environment (JRE) with minimum version 17. This does not come included with Kroxylicious. |
| 17 | + |
| 18 | +Some operating systems come with a JRE already installed. You can check what Java version you have installed by running the following command: |
| 19 | + |
| 20 | +```shell |
| 21 | +java -version |
| 22 | +``` |
| 23 | + |
| 24 | +{% capture jre_note %} |
| 25 | +If you get an error or the command doesn't return anything, you may not have a JRE installed, or your JRE may not have been correctly added to your system's `PATH` variable. |
| 26 | +{% endcapture %} |
| 27 | + |
| 28 | +{% include bs-alert.html type="primary" icon="info-circle-fill" content=jre_note %} |
| 29 | + |
| 30 | +#### Apache Kafka® |
| 31 | + |
| 32 | +You will also need a running Apache Kafka® cluster for Kroxylicious to proxy. The official Apache Kafka® [quickstart](https://kafka.apache.org/documentation/#quickstart) has instructions for setting up a local bare metal cluster. |
| 33 | + |
| 34 | +Once your cluster is set up, the cluster bootstrap address used by Kroxylicious can be changed in the configuration YAML file (see the [**Configure**](#configure) section below). |
| 35 | + |
| 36 | +<br /> |
| 37 | + |
| 38 | +### Downloading Kroxylicious |
| 39 | + |
| 40 | +Kroxylicious can be downloaded from the [releases](https://github.com/kroxylicious/kroxylicious/releases) page of the Kroxylicious GitHub repository, or from Maven Central. |
| 41 | + |
| 42 | +In GitHub, all releases since v0.4.0 have an attached `kroxylicious-app-*-bin.zip` file. Download the latest version of this zip, and optionally verify the contents of the package with the attached `kroxylicious-app-*-bin.zip.asc` file. |
| 43 | + |
| 44 | +{% capture os_archive_note %} |
| 45 | +If you're trying Kroxylicious out on Linux or macOS, you may find the `.tar.gz` format easier to work with. We're using the `.zip` files in this quickstart for cross-platform compatibility, but we recommend you use whichever format you're most familiar with. |
| 46 | +{% endcapture %} |
| 47 | + |
| 48 | +{% include bs-alert.html type="primary" icon="info-circle-fill" content=os_archive_note %} |
| 49 | + |
| 50 | +<br /> |
| 51 | + |
| 52 | +# Install |
| 53 | + |
| 54 | +Extract the downloaded Kroxylicious Zip file into the directory you would like to install Kroxylicious in. |
| 55 | +Ensure the `kroxylicious-start.sh` and `run-java.sh` files in the `bin/` directory within the extracted folder have at least read and execute (`r-x`) permissions for the owner. |
| 56 | + |
| 57 | +<br /> |
| 58 | + |
| 59 | +# Configure |
| 60 | + |
| 61 | +Kroxylicious is configured with YAML. From the configuration file you can specify how Kroxylicious presents each Apache Kafka® broker to clients, where Kroxylicious will locate the Apache Kafka® cluster(s) to be proxied, and which filters Kroxylicious should use along with any configuration for those filters. |
| 62 | + |
| 63 | +An example configuration file can be found in the `config/` directory of the extracted Kroxylicious folder, which you can either modify or use as reference for creating your own configuration file. |
| 64 | + |
| 65 | +For this quickstart we will use Kroxylicious in Port-Per-Broker configuration, and assume that both your Apache Kafka® cluster and clients are running on your local machine and using their default configuration. This means we can use the example proxy config file that comes with Kroxylicious. |
| 66 | + |
| 67 | +If your machine uses a non-standard port configuration, or if you have used custom settings for your Apache Kafka® cluster (or if your cluster is running on a different machine) you will need to adjust your Kroxylicious configuration accordingly. More information about configuring Kroxylicious can be found in the [documentation](https://kroxylicious.io/kroxylicious/#_deploying_proxies). |
| 68 | + |
| 69 | +<br /> |
| 70 | + |
| 71 | +# Run |
| 72 | + |
| 73 | +From within the extracted Kroxylicious folder, run the following command: |
| 74 | + |
| 75 | +```shell |
| 76 | +./bin/kroxylicious-start.sh --config config/example-proxy-config.yml |
| 77 | +``` |
| 78 | + |
| 79 | +To use your own configuration file instead of the example, just replace the file path after `--config`. |
| 80 | + |
| 81 | +<br /> |
| 82 | + |
| 83 | +# Use |
| 84 | + |
| 85 | +To use your Kroxylicious proxy, your client(s) will need to point to the proxy (using the configured address) rather than directly at the Apache Kafka® cluster. |
| 86 | + |
| 87 | +[//]: # (====================================================================) |
| 88 | +[//]: # (START - Use Section Examples Tabbed Card) |
| 89 | +[//]: # (====================================================================) |
| 90 | + |
| 91 | +[//]: # (The element ID for this nested tabbed card, used for everything that makes nesting cards and having tabs work) |
| 92 | +[//]: # (We prepend the ID of the parent card tab - i.e. this file - to this element ID to ensure it is unique) |
| 93 | +{% capture use_examples_htmlid %}{{ page.htmlid }}-useExamples{% endcapture %} |
| 94 | + |
| 95 | +{% capture apacheClientContent %} |
| 96 | +In each command below, substitute `$KROXYLICIOUS_BOOTSTRAP` for the bootstrap address of your Kroxylicious instance. |
| 97 | + |
| 98 | +<br /> |
| 99 | + |
| 100 | +##### 1. Create a topic via Kroxylicious |
| 101 | +Create a topic called "my_topic" using the `kafka-topics.sh` command line client: |
| 102 | +```shell |
| 103 | +bin/kafka-topics.sh --create --topic my_topic --bootstrap-server $KROXYLICIOUS_BOOTSTRAP |
| 104 | +``` |
| 105 | + |
| 106 | +<br /> |
| 107 | + |
| 108 | +##### 2. Produce a string to your topic via Kroxylicious |
| 109 | +Produce the string "hello world" to your new topic using the `kafka-console-producer.sh` command line client: |
| 110 | +```shell |
| 111 | +echo "hello world" | bin/kafka-console-producer.sh --topic my_topic --bootstrap-server $KROXYLICIOUS_BOOTSTRAP |
| 112 | +``` |
| 113 | + |
| 114 | +<br /> |
| 115 | + |
| 116 | +##### 3. Consume your string from your topic via Kroxylicious |
| 117 | +Consume your string ("hello world") from your topic ("my_topic") using the `kafka-console-consumer.sh` command line client: |
| 118 | +```shell |
| 119 | +bin/kafka-console-consumer.sh --topic my_topic --from-beginning --bootstrap-server $KROXYLICIOUS_BOOTSTRAP |
| 120 | +``` |
| 121 | +{% endcapture %} |
| 122 | + |
| 123 | +{% capture kafClientContent %} |
| 124 | +In each command below, substitute `$KROXYLICIOUS_BOOTSTRAP` for the bootstrap address of your Kroxylicious instance. |
| 125 | + |
| 126 | +<br /> |
| 127 | + |
| 128 | +##### 1. Create a topic via Kroxylicious |
| 129 | +Create a topic called "my_topic" using Kaf: |
| 130 | +```shell |
| 131 | +kaf -b $KROXYLICIOUS_BOOTSTRAP topic create my_topic |
| 132 | +``` |
| 133 | + |
| 134 | +<br /> |
| 135 | + |
| 136 | +##### 2. Produce a string to your topic via Kroxylicious |
| 137 | +Produce the string "hello world" to your new topic: |
| 138 | +```shell |
| 139 | +echo "hello world" | kaf -b $KROXYLICIOUS_BOOTSTRAP produce my_topic |
| 140 | +``` |
| 141 | + |
| 142 | +<br /> |
| 143 | + |
| 144 | +##### 3. Consume your string from your topic via Kroxylicious |
| 145 | +Consume your string ("hello world") from your topic ("my_topic"): |
| 146 | +```shell |
| 147 | +kaf -b $KROXYLICIOUS_BOOTSTRAP consume my_topic |
| 148 | +``` |
| 149 | +{% endcapture %} |
| 150 | + |
| 151 | +[//]: # (These IDs need to be identical across the tab elements and the tab content elements, so we declare them here to avoid confusion) |
| 152 | +[//]: # (We prepend the ID of the parent element to these IDs to ensure they are unique) |
| 153 | +{% capture apache_htmlid %}{{use_examples_htmlid}}-apacheClient{% endcapture %} |
| 154 | +{% capture kaf_htmlid %}{{use_examples_htmlid}}-kafClient{% endcapture %} |
| 155 | + |
| 156 | +{% capture use_example_tabs %} |
| 157 | +{% include nested-card-tabbed/tab.html htmlid=apache_htmlid is_active_tab=true tab_title="Using Kroxylicious with the Apache Kafka® command line clients" %} |
| 158 | +{% include nested-card-tabbed/tab.html htmlid=kaf_htmlid is_active_tab=false tab_title="Using Kroxylicious with the [Kaf](https://github.com/birdayz/kaf) command line client" %} |
| 159 | +{% endcapture %} |
| 160 | + |
| 161 | +{% capture use_example_content %} |
| 162 | +{% include nested-card-tabbed/tab-content.html htmlid=apache_htmlid tabindex=0 is_active_tab=true content=apacheClientContent %} |
| 163 | +{% include nested-card-tabbed/tab-content.html htmlid=kaf_htmlid tabindex=1 is_active_tab=false content=kafClientContent %} |
| 164 | +{% endcapture %} |
| 165 | + |
| 166 | +{% include nested-card-tabbed/card.html htmlid=use_examples_htmlid tabs=use_example_tabs content=use_example_content %} |
| 167 | + |
| 168 | +[//]: # (====================================================================) |
| 169 | +[//]: # (END - Use Section Examples Tabbed Card) |
| 170 | +[//]: # (====================================================================) |
0 commit comments