The simplest OSGi / Karaf hello, world demo I could come up with

I don’t know about you, but I almost gave up looking for quick and lightweight examples on how to get started creating and deploying an OSGi bundle. Everything I found used out of date or opaque Maven plugins, proprietary techniques specific to a platform, magic tooling called “bnd,” and all kinds of other chaos. I repeatedly hear that precisely this chaos slows down OSGi adoption and related technologies like Camel. I hope this post speeds you up a little.

First, let’s write some Hello, World code

This is the easiest part. I just wanted a simple example that prints hello, world to the console when the bundle starts. Here’s the code I came up with:

You probably noticed you’re going to need the OSGi framework on your classpath. Here are the dependencies I used (but I haven’t researched whether both are strictly necessary or not):

UPDATE (August 2019): Please see Paul’s comment below noting that the the artifacts I listed below are pretty old. He reported that he fixed the issue by adding a line to the manifest file: “fix[ed] this by adding ‘Bundle-ManifestVersion: 2’ to the MANIFEST.MF file.”

Hand craft a file – You. Can. Do. It.

This was the big hurdle for me. It seems that most of the authors of the examples I found had some kind of allergy to hand writing the file, so they rely on various tooling to write it and bundle it. I suppose in real life I might get used to the tooling, but it just gets in the way of me learning. So here’s my hand crafted file:

Bundle-SymbolicName and Bundle-Version lets you describe what the bundle will look like to a user in Karaf (or whatever OSGi container, I suppose). For example:


Import-Package is critical. In fact, it’s a core part of the OSGi concept that you must explicitly declare the services you’re depending on. Remember how we imported the OSGi dependencies in the hello, world Java code? You might have thought that installing a bundle would implicitly include the framework, but you’d be wrong. You have to explicitly declare it.

Export-Package is a similar concept. You need to expose your services to other bundles. Finally, Bundle-Activator is the class you want to fire up on start (the hello, world code above).

Also (Aug 2019 update): see note from above that now that those artifacts are getting a little old you may need to add a Bundle-ManifestVersion: 2 line as well, but I haven’t tried this for myself.

Structuring your project

I put my manifest file under src/main/resources/META-INF:


The wrinkle here is that Maven will overwrite your META-INF file unless you override the default behavior with this:

Finally. Now let’s install and start the bundle

I ran this in Karaf, so here’s what I did. First, run mvn install to get the artifact into your local repository. Next, start up Karaf and run this command:


Take note of the bundle ID. Mine was 95 in this example, but it varies each time. Now let’s start it with this command:

And you should see something like this:


The full example is here: Good luck out there.

24 replies on “The simplest OSGi / Karaf hello, world demo I could come up with”

Thanks for this posting. The initial paragraph reflects my experience perfectly. I was beginning to despair of ever picking up what seemed to be a straight-forward technology. You have restored my faith in OSGI – well, for the time being anyway 🙂


Thanks so much for the nice comment Steve!

I should probably write an update to this post sometime. The guy who wrote the BND tool gave me a hard time on Twitter about this post explaining that the manifest really can’t be managed without some kind of tooling.

That said, I took some Red Hat training a few weeks back with Scott England-Sullivan, one of the Karaf committers, and he completely sold me on declarative services as a much, much easier way to do this.

If you can, search for his talk from Devnation 2014. If I had the link handy, I’d send it over.

thank you! you have removed to a great deal, the cloud that surrounded osgi. I was so apprehensive about writing a simple project.

HI michael,
Thank you for the Great Article , I want do same thing using blueprint.xml can you please Guide me how to achieve?


Hi Santosh! Thanks for the comment. Unfortunately, it’s been a while since I did this so I’d have a hard time guiding you now. Good luck though

Thanks for the vote of confidence, Michael! Not sure it’s fair to call the tooling “shaving the yak,” but I do like my beginning examples to be as clean cut as possible.

Hey Tehmina,

Sorry I’m just now replying. I think there are lots of great tutorials out there. My only goal was to do a really simple, stripped down example. It’s obviously not what you’d want to do in a production — but I hope it helps you learn!

Sorry, but the post is awful.
1. You should use correct artifact of osgi: org.osgi:org.osgi.framework
2. You should never edit manually, the plugin org.apache.felix:maven-bundle-plugin is created specially for that.
3. Using “karaf install” you are installing the bundle from local maven repository, but what if I do not put my jar in repository?
You should notice that user must install artifact in the local maven repository (and karaf must reference to that repository), or user must install artifact to karaf system repository (mvn … -Durl=/system), or user should use hot deploy (via putting artifact in deploy directory).

Hey Vasya,

First of all, thanks for taking the time to post some good ideas. I hope future readers will benefit from them. I’m far removed from the platform these days, so I can’t engage you at a technical level.

However, I do want to engage you on your unhelpful opinion that “the post is awful.” I don’t care what you say to me — I’ve been around a long time and, frankly, your comment reflects a lot more on you than it does me. What I don’t like is that you’re contributing to a toxic culture that does nothing but hold people back with comments like yours.

Aside from people who’ve developed thick skin, like me, who would want to put their opinions out there with your immature reaction?

What junior programmer with some awesome, but half-baked, idea will post it when they risk having to deal immature comments like yours?

You do nothing but damage the industry in the process. I wrote a whole blog post on Tech Lead Daily about it. (So thank you for the material, I guess.)

When you’re ready for it, I’m happy to offer you some free tech lead coaching. You’ve got good ideas, so let’s just work on that first sentence 😉

Hi,Thanks for posting this article.I have followed steps as you said but Im getting error while installing app in karaf as-
“Error executing command: Error installing bundles:
Unable to install bundle mvn:psl.karaf.karafDemo/osgi-example/0.0.1.SNAPSHOT: org.osgi.framework.BundleException: Unable to cache bundle: mvn:psl.karaf.karafDemo/osgi-example/0.0.1.SNAPSHOT”

Hi Nikhil,

Wish I could help! It’s been a while since I touched these technologies so I’d probably give you the wrong answer even if I could attempt at it. Sorry buddy but good luck! (And thanks for taking the time to comment, maybe others will have some ideas……)


Thanks for the useful post!

I had been trying for days just to get a simple OSGi ‘Hello World’ program working but with no success.

I tried this tutorial today and it worked fine!

I agree with you about the tooling aspect of OSGi being unnecessarily difficult when one is starting out.
I’m beginning to learn how to use OSGi, and the tooling seems to make OSGi very complicated.

Hi michael.
Can you please suggest
how i can deploy flowable war file inside apache
karaf container
since flowable war file is working fine in apache tomcat
but not in apache karaf


Hi Ravi, wish I could help. This post is getting petty old and it’s been a long time now since I’ve worked on the technology so don’t know the answer to your question.

Hi there,

I found this very useful but I came across an issue when installing the bundle in Karaf. It was displaying the following error:

org.osgi.framework.BundleException: OSGi R3 bundle not supported

I managed to fix this by adding “Bundle-ManifestVersion: 2” to the MANIFEST.MF file.

Could you update your tutorial to include Paul’s fix for the install error? I had the same issue and spent much time researching until I came to the same solution independently. Then I read all the comments.

Also I found that the dependencies in the POM should be updated to just one dependency of :

As the saying goes “No good deed goes unpunished” and the internet lives on forever.

Thanks for the article,

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.