In this post I’ll explain how you can use docker to facilitate your developments and deployments when working with apache Karaf.
To help you run the examples in this article, I’ve created this github repository. It consists of a Maven multimodule project :
- karaf-sandbox : parent module. Also contains docker definitions
- karaf-sandbox-distribution : karaf custom distribution packaging
- karaf-sandbox-rest : a custom rest service that exposes /api/message http endpoint to post and get messages.
This post walks through the following sections :
- Karaf provisioning
- How to create your custom karaf distribution
- How to run your karaf distribution with docker
By karaf provisioning, we means : how to deploy and run your custom code in karaf ?
Karaf is a powerful osgi runtime environment which you can use to run your java apps : web applications, api, integration services… There are several ways to deploy your code in karaf. It is described here in the official documentation.
To sum up, the recommanded way to provision a karaf server is to package your application code as osgi features, then to install these features using karaf shell commands.
So the workflow for provisioning a karaf server from scratch would be something like this :
- Download karaf server archive from Download karaf server
- Unpack the karaf server and starts it by lauching
- Connect to the karaf shell by launching
- Install the features repositories needed (ie. where to find the features)
- Install the features you need
For instance, if I want to install
camel-core in my karaf server, I will first connect to my karaf shell console, then use these two commands :
According to me this method has a huge drawback in a container world. Let’s say you have a container to manage your karaf server, each time you will have to install a feature in it, you will modify your container by applying configuration in it, breaking the rule of idempotence a container should follow.
To respect idempotence, it would be better to package your karaf server with all features you need, then build it and run it as container.
Fortunatly, karaf offers a way to package your own karaf server distribution
- You need to have a valid maven installation to run following examples
- Current version of karaf at the time of writing this article is
You can generate your own karaf distribution by using the maven archetype :
For the purpose of this article, we will init a
karaf-sandbox-ditsribution project will consists of a karaf standard installation packaged with hawtio web console.
Init your custom distribution
Launch the following command from this directory to init the karaf distribution (Change groupId, package, … according to your needs).
This command will generate a directory
karaf-sandbox-distribution with a well formatted
pom.xml in it.
In the generated
pom.xml you’ll find the following insteresting parts :
- packaging :
- dependencies : all the dependencies listed here will be included in the generated package.
- karaf-maven-plugin : you can configure the features you want to install
Then, if you launch a maven install for this project, this will package a karaf server in your
target directory. You’ll find here :
assemblydirectory : your karaf server
tar.gz: your karaf server packaged as tar
zip: your karaf server packaged as zip
You will be able to start your karaf server by launching
bin/karaf command directly from the
target/assembly directory (provided that you have a valid installation whith
JAVA_HOME env variable parametred).
Add your custom features
hawtio feature to your karaf distribution, you will need to add the
hawtio xml features dependency in the maven dependencies, then add the feature
hawtio-offline, the one I use in this article) to the boot features, so that I will be installed during karaf boot.
I also removed the
wrapper feature from
installedFeatures section, because I installs a lot of default features I don’t need.
Now if you re-install your project with maven, and start it, hawtio will be installed and you will be able to connect to hawtio web interface : http://localhost:8181/hawtio.
Same could be done with your custom application code. Just package your application code as osgi features, then add the repository xml feature in dependencies section, and finally add your custom features to bootFeatures list.
Now that we know how to package a custom karaf distribution, we can focus on how to run it with docker.
What we want :
- Docker should launch maven build (so that I don’t need to have maven installed on host)
- Docker should builds an image from karaf generated tar archive
- Docker should expose karaf used ports :
- 8101 : Karaf ssh default port.
- 8181 : Karaf http default port.
Here is the
Dockerfile I use to build my image :
Dockerfile use a docker multi-stage build, to provide a minimal image :
first part of the dockerfile is just used build the Karaf distribution with maven.
Build image and run container with compose
To build and run this karaf sandbox container you can use
docker-compose with the following
docker-compose.yml file :
Build your docker image with this command :
Run a docker container with this command :
Check that your container is running :
To read karaf logs :
Then you can access your container hawtio with this url : http://localhost:8181/hawtio/login
Here we are, you have a custom karaf distribution running in docker container ! To go further, I will explain you how to scale this docker service in a future article.
This article has been inspired in part by the following projects or articles :