This 10-minute guide will show you how to run an entire Hermes environment, create topic and subscription and publish some messages.
There are two ways of setting up the environment: using vagrant or docker.
In order to go through this tutorial you need to have:
As described in architecture section, Hermes consists of multiple modules and requires Kafka and Zookeeper to run. To make this easy, we prepared a Vagrant file.
git clone https://github.com/allegro/hermes.git
cd hermes
vagrant up
If you want to run specific version of Hermes, simply checkout a tag:
git checkout hermes-{version}
If the system is running, you should see Hermes Console when visiting Vagrant public IP in the browser. Just head to http://10.10.10.10/.
If you want to run hermes with docker, you need to have:
In order to run hermes in docker, you need to have the docker-compose file that can be found here.
After downloading the file simply run this command inside the directory where the file is located:
docker-compose up
This may take up to several minutes as all docker images need to be downloaded from docker servers.
Hermes console should be up and running on port 8090. Simply head here.
All hermes images can be found under these links: * hermes-management * hermes-frontend * hermes-consumers
If you want to run a specific hermes release simply add a given version to the image name inside the docker-compose file, for example:
image: allegro/hermes-management:hermes-[specific version tag]
Now you're ready to create a topic for publishing messages.
In Hermes messages are published on topics which are aggregated into groups.
So, you'll need to create a group first, let's name it com.example.events
.
com.example.events
At this point, you should see your group on the group list. Now let's add new clicks
topic to our group:
clicks
To receive messages that are published on topic you have to create a subscription. This is where you tell Hermes where to send messages published on a topic. You can have many subscriptions on a single topic (in particular - none).
So let's create a clicks-receiver
subscription:
clicks-receiver
http://webhook.site/aa715639-e85d-43b4-9a29-ec46824021fe
Now it's time for a grand finale. Let's publish a message on our topic (note that default Hermes publishing port is 8080
):
curl -v -d '{"id": 12345, "page": "main"}' http://10.10.10.10:8080/topics/com.example.events.clicks
< HTTP/1.1 201 Created
< Hermes-Message-Id: 66feaead-0685-491e-9c87-00f940ead2c9
< Content-Length: 0
< Date: Mon, 04 May 2015 02:18:23 GMT
(the first time you publish something you might see 408 Request Time-out status: a lot of machinery needs to warm up, just hit retry)
Congratulations! The message should be delivered to your service or visible via e.g. http://webhook.site/#!/aa715639-e85d-43b4-9a29-ec46824021fe/71377cf3-9076-4c06-b3ef-ec779170ce05/1.
To stop the virtual machine run:
vagrant halt
Run it again with:
vagrant up
Destroy the VM with:
vagrant destroy
To stop the system run this command in the directory where the docker-compose file is located:
docker-compose stop
To restart it run:
docker-compose restart
You can build your own docker image for a specific module and later test it for example in docker-compose.yml
.
Simply run this command from a hermes project root directory:
docker build --tag [your tag name] -f ./docker/latest/[hermes module]/Dockerfile .
For example:
docker build --tag hermes-management-test -f ./docker/latest/management/Dockerfile .
The built image can be tested directly in docker-compose.
You need to replace image name with your tag name in docker-compose.yml
:
[...]
management:
image: [your tag name]
ports:
- "8090:8090"
depends_on:
- zk
- kafka
- graphite
[...]
Docker files for specific hermes modules can be found in docker/latest
directory.