Building Your Equinox OSGi Application Server – Part 1

Building Your Equinox OSGi Application Server – Part 1

Over the past year I’ve developed a goal of making it easier to build and deploy the Equinox runtime as a web application server.  Not only does this fit my technical skills having previously worked on a commercial application server, it also fits my technical interests. It also seems that an ever increasing set of other people have been interested in running the Equinox OSGi runtime as a application server. Furthermore, many people may not be aware that there are now a number of really excellent  technologies available via the EclipseRT project that are relevant to creating modern application servers:

There’s a lot more to come, for example, ECF’s work on supporting Google Wave server protocol as well as commercial technologies from EclipseSource and other technology companies devoted to the OSGi stackless stack.

However, in my opinion it’s far more difficult to build, deploy, configure and run an Equinox server than it should be.  There is existing documentation on doing so from scratch here, but it is a little dated.  I am contributing to the Equinox project to get the documentation updated with community help.

So, I would like to do a short set of blogs about building your own Equinox-based application server.  Hopefully this will be helpful to those who are interested. It’s possible to create two ‘kinds’ of Equinox-based application servers. Those that are actually run stand-alone (i.e., as a Equinox OSGi application) or those that are run within an existing servlet container such as Jetty or most commercial application servers.  For this series, I’m going to focus on the servlet container method as I think this will ultimately be the more common and popular method. Furthermore, servlet containers now make deployment, installation and configuration very easy (which goes a long way toward my goal).

Ok, so how to create an Equinox-based application server?  Well, with the Eclipse Galileo PDE build, p2, features, and products, it turns out it’s now very easy to do so (compliments to the particularly to the folks who worked on PDE, Equinox, and P2 in this area).  I’ve created a simple feature and product that does so and contributed them to this bug.  Here are the steps:

1) Download the zip attached to bug 245267

2) In Eclipse, open a new workspace and import the projects from the downloaded zip (File->Import…->Existing Projects in Workspace->Select Archive File).  This will put two very small projects into your workspace


3) There are two other projects (from Equinox CVS area) required before you can create your app server.  To add these projects right click on the equinox-servletbridge.psf file and select Import Project Set…  from the menu (use anonymous CVS login when prompted).  Now you should have four projects in the workspace


4) Now, open the PDE product editor by double clicking on equinox-milli.product file

5) Select Eclipse product export link in lower right of product editor


6) In the export wizard dialog set the following fields

a) The Root Directory field must be set to:  WEB-INF

b) The Synchronize before exporting check box can be unchecked

c) The Destination must be set to Archive file, and given a location/name of your choosing (e.g.

d) The Generate metadata repository should be checked (to include p2 metadata)


e) Click Finish

This will run PDE build and create a zip named (in the above case):

6) Now comes the fun part.  Simply rename this zip file to a .war…i.e. myappserver.war

7) Start your servlet container (in this case I’m using tomcat)


8) Hot deploy the war file (in this case myappserver.war) in the manner appropriate for your servlet container (in tomcat’s case this is copying the myappserver.war file into the webapps directory).  After a few seconds, you should see something like the following output to the tomcat console…with the nice little osgi> prompt, indicating your Equinox server is deployed and running!


9) Give some OSGi console commands with the osgi> prompt just to convince yourself everything is working…e.g.


10) Go show your colleagues how easy it was to create, deploy and run your Equinox application server!

There’s a lot more that you can now do with your Equinox application server like:

  • Adding servlets (via bundles)
  • Using P2 to update your application server
  • Creating your web applications in a modular fashion using bundles and features
  • Reuse your favorite bundles from Eclipse or other projects
  • Deploy and maintain your web application as bundles (and using PDE to do it)

In the future, I’ll describe how to do some of these things.

If people are interested in particular things to do, please comment and let me know.

  • Posted at 20:38, 2009-08-15


    Great that you’re writing this series on how to build an Equinox based Appserver together with a ServletContainer like Tomcat.

    I’m just preparing a blog series about the other part: a standalone OSGI-Equinox based Appserver supporting RCP Apps using Riena. Its good to see how Equinox is now used as an Appserver Platform together with many great Eclipse Projects.

    I’m also interested in your way of use it with ServletContainer, because later my enterprise project will not only support RCP clients, but also Web Clients, Mobile Clients and WebServices.

    At the moment its fascinating for my customers to see flexibility of an OSGI based Server, just yesterday demonstrated to run the Riena RCP Client, then to design a Business View (EMF based SWT using redView) outside the app, update one bundle, refresh another one from console and the new designed View is visible without restarting.

    …its a great technology – not only fun to developrs – also for users of the products (and they are where the money comes from 😉

  • Posted at 00:20, 2009-08-16

    Very cool, Scott. Thanks for this and I look forward to more on this series.

    Definitely excited about the potential of p2 in this equation. We really need to showcase this to the community. And it’s one of the big features that makes me believe Equinox standalone in something like an Eclipse OS could make it a winner.

  • Peter Chilcott
    Posted at 09:25, 2009-08-16

    Yep, this technique is something I’ve been interested in seeing crystalised for quite a while and it’s most valuable.

    Would like to see it refactored into something genuinely straight forward. Nice one Scott!

  • Posted at 10:52, 2009-08-17

    For those who are interested in using this approach together with RAP, I prepared a small feature+product based demo using Scott’s work to deploy RAP applications.

    In addition we tried to reuse the existing product editor for proper validation and export of war-archived equinox apps, see this bug.

  • Matthias Erche
    Posted at 10:22, 2009-08-20

    Hi Scott,

    thanks a lot for this series!

    I’m new to the topic and just wonder how non- Eclipse web frameworks like Struts or something similar do integrate in such an infrastructure. Do you have any experiences on that?

  • Alex Blewitt
    Posted at 20:12, 2009-08-22

    I gave a demo using the servletbridge recently from the Equinox wiki. However, it linked to bridge.war, which contained Eclipse 3.2 as the runtime. Would be good if that could be updated to a more recent version of Eclipse, even if using Equinox as is (rather than the servlet bridge) is recommended.

  • Posted at 21:21, 2009-08-22

    Hi Alex,

    I agree. I’ve offered to contribute/update the pages on the website and wiki to use the new version of servletbridge and building with product as per I would recommend you join that bug and make your desires known about update on the documentation, as I do not have Equinox committer rights.

  • Santosh B
    Posted at 01:21, 2009-08-28

    It is pushing OSGI towards integrating it with the popular web world. Do u see major app server one day can itself become a bundle and can be install/uninstall,start/stop using osgi command. After reading OSGI spec and briefly about few of the implementation like equinox, felix, i found this article very informative.

  • Posted at 15:20, 2009-08-28

    Hello Santosh. I agree that OSGi is integrating with the web server world. Actually, today, most of the major app server vendors *already* use OSGi under the covers…to manage dynamic requirements of the server (e.g. bundles/versions coming and going). So in a sense, the major app server vendors are already there. To my knowledge, what the app server vendors are *not* doing (yet) is exposing the OSGi programming model (bundles and services) to webapp developers.

  • Posted at 11:42, 2010-02-25

    Quite helpful was developing our OSGi Remote Console with Apache Mina, see , which worked around some limitations of the original OSGi remote console. It is not perfect but might help a little bit.

  • amsayk
    Posted at 04:25, 2010-04-22

    Hi, thanks for the tutorial.

    I’m newbie in equinox and osgi. but i want to develop a simple webapp as a bundle and deploy it in the myappserver above using the http extension registry. i registered a servlet and a resources like

    in plugin.xml

    i then added this bundle to a feature and added that feature to the milli server, exported it and deployed it in jetty. but navigating to /ext/helloword.html and /ext/helloworld can’t be resolved by jetty(404).

    i guess its just something i missed. any ideas…