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.

15 Responses to “Building Your Equinox OSGi Application Server – Part 1”

  1. ekke says:


    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 ;-)

  2. Scott Lewis says:

    Hi Ekke,

    Yeah I agree that making Equinox on server easier is a worthy goal for the runtime projects. If you wish to refer to these entries in your blog please feel free. I’ll do the same.

    RE: managing OSGi servers…yes, I agree this has some unique value. One of my future posts will involve using P2 to manage/install/update sets of bundles in running Equinox server….and describing how Jeff’s Remote Provisioning post was done using remote services.

  3. 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.

  4. Scott Lewis says:

    Hi Doug,

    You probably noticed that p2 is included in the configuration shown in this blog post…I’m likely going to have a full post just on how to use p2 to install/uninstall/update a running appserver. As well as something around using p2 and ECF remote services to do remote p2 provisioning (Jeff’s video).

    So anyway, thanks for the feedback…I agree strongly about p2 and servers…and will raise the priority of that entry.

  5. Peter Chilcott says:

    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!

  6. Scott Lewis says:

    Hey Peter. I’m curious about what you have in mind WRT “refactored into something genuinely straightforward.”

    Do tell!

  7. 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.

  8. Matthias Erche says:

    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?

  9. Scott Lewis says:

    Hi Matthias,

    Thanks for the nice words. RE: web frameworks like struts, etc…yes…many of these frameworks now support being distributed as OSGi bundles. Once such frameworks are in bundle form (or can easily be put into bundle form), then they can be incorporated into the application server as described in post 2 very easily. The Orbit project at Eclipse: has a number of libraries/frameworks from the Apache project and others…that have already been converted to bundles.

  10. Alex Blewitt says:

    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.

  11. Scott Lewis says:

    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.

  12. Santosh B says:

    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.

  13. Scott Lewis says:

    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.

  14. ctron says:

    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.

  15. amsayk says:

    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…

15 responses so far

Written by . Published in Categories: Planet Eclipse

Looking for a job?

Karlsruhe / Remote
Karlsruhe / Victoria / Remote
Karlsruhe / Victoria / Remote