## Prerequisites
1. Make sure Apache Kafka is running. You can start it by following instructions from [here](https://karafka.io/docs/Kafka-Setting-Up.md).
## For Existing Applications
1. Add Karafka to your Gemfile:
```bash
# Make sure to install Karafka 2.5 as Karafka 1.4 is no longer maintained
bundle add karafka --version ">= 2.5.0"
```
2. Install Karafka (works for both Rails and standalone applications) by running:
```bash
bundle exec karafka install
```
the above command will create all the necessary files and directories to get you started:
- `karafka.rb` - main file where you configure Karafka and where you define which consumers should consume what topics.
- `app/consumers/example_consumer.rb` - example consumer.
- `app/consumers/application_consumer.rb` - base consumer from which all consumers should inherit.
3. After that, you can run a development console to produce messages to this example topic:
```ruby
# Works from any place in your code and is thread-safe
# You usually want to produce async but here it may raise exception if Kafka is not available, etc
Karafka.producer.produce_sync(topic: 'example', payload: { 'ping' => 'pong' }.to_json)
```
4. Run the karafka server to start consuming messages:
```
bundle exec karafka server
# example outcome
[7616dc24-505a-417f-b87b-6bf8fc2d98c5] Polled 2 messages in 1000ms
[dcf3a8d8-0bd9-433a-8f63-b70a0cdb0732] Consume job for ExampleConsumer on example started
{"ping"=>"pong"}
{"ping"=>"pong"}
[dcf3a8d8-0bd9-433a-8f63-b70a0cdb0732] Consume job for ExampleConsumer on example finished in 0ms
```
Here's the demo of the installation process:
Note: Asciinema videos are not visible when viewing this wiki on GitHub. Please use our
online
documentation instead.
5. (Optionally) Install and configure the Web UI by following [this](https://karafka.io/docs/Web-UI-Getting-Started.md) documentation section.
## For New Applications (Starting From Scratch)
If you're starting with an empty directory:
1. First create a `Gemfile`:
```ruby
# Gemfile
source "https://rubygems.org"
gem "karafka", ">= 2.5.0"
```
2. Run: `bundle install`
3. Install Karafka (works for both Rails and standalone applications) by running:
```bash
bundle exec karafka install
```
the above command will create all the necessary files and directories to get you started:
- `karafka.rb` - main file where you configure Karafka and where you define which consumers should consume what topics.
- `app/consumers/example_consumer.rb` - example consumer.
- `app/consumers/application_consumer.rb` - base consumer from which all consumers should inherit.
4. After that, you can run a development console to produce messages to this example topic:
```ruby
# Works from any place in your code and is thread-safe
# You usually want to produce async but here it may raise exception if Kafka is not available, etc
Karafka.producer.produce_sync(topic: 'example', payload: { 'ping' => 'pong' }.to_json)
```
5. Run the karafka server to start consuming messages:
```
bundle exec karafka server
# example outcome
[7616dc24-505a-417f-b87b-6bf8fc2d98c5] Polled 2 messages in 1000ms
[dcf3a8d8-0bd9-433a-8f63-b70a0cdb0732] Consume job for ExampleConsumer on example started
{"ping"=>"pong"}
{"ping"=>"pong"}
[dcf3a8d8-0bd9-433a-8f63-b70a0cdb0732] Consume job for ExampleConsumer on example finished in 0ms
```
## Example applications
If you have any problems setting things up or want a ready application to play around with, then the best idea is just to clone our examples repository:
```bash
git clone https://github.com/karafka/example-apps ./example_apps
```
and follow the instructions from the [example apps Wiki](https://github.com/karafka/example-apps/blob/master/README.md).
## Use-cases, edge-cases, and usage examples
Karafka ships with a full integration test suite that illustrates various use-cases and edge-cases of working with Karafka and Kafka. Please visit [this directory](https://github.com/karafka/karafka/tree/master/spec/integrations) of the Karafka repository to see them.
---
*Last modified: 2025-06-16 12:29:46*