In the process of trying to learn about Apache Karaf I put together a set of skeleton projects (based on Karaf 2.2.4) that help to bootstrap a custom distribution. The end goal is a standalone Karaf installation that includes your application bundle(s) in a standalone archive that can be deployed to a Maven-less, Internet-less machine. Your custom deployment is wrapped up in a single ZIP file with all dependencies embedded.
There's nothing new here, just a distillation of docs, mailing list threads, Maven wrangling and the like. You're still need to going to write your application.
The sub-projects are:
- com.custom.branding : Resource-only bundle that customizes the Karaf console shell per the instructions.
- com.custom.karafbundle : Simple Java OSGi bundle with the obligatory Hello World
- com.custom.karafhost : The "host" installation. A Karaf installation, including both OSX and Windows shell scripts, will be downloaded and pre-populated with the custom set of bundles. Eclipse Run Configurations that delegate to the downloaded platform shell scripts are included as external files in the project.
- com.custom.karafservlet : PAX Whiteboard registered servlet at "/hello" which outputs, unoriginally, Hello World.
- com.custom.scalabundle : Scala implementation of simple Hello World OSGi bundle.
For Eclipse Building:
For Scala integration:
- Scala IDE for Eclipse (Optional)
- From a command prompt in the com.custom.karafhost directory, enter "mvn install"
- Navigate to the .../com.custom.karafhost/target/karaf/apache-karaf-2.2.4/bin directory and launch your platform-specific karaf.* shell script.
- From the com.custom.karafhost project context menu, select Run As -> Maven Install
- Assuming all goes well, you should see something like:
[INFO] Custom :: Karaf :: Java Bundle .................... SUCCESS [1.988s]
[INFO] Custom :: Karaf :: Scala Bundle ................... SUCCESS [2.935s]
[INFO] Custom :: Karaf :: Java Servlet ................... SUCCESS [0.525s]
[INFO] Custom :: Karaf :: Console Branding ............... SUCCESS [0.459s]
[INFO] Custom :: Karaf :: Distribution ................... SUCCESS [12.737s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 19.324s
[INFO] Finished at: Mon Dec 26 15:39:57 PST 2011
[INFO] Final Memory: 15M/123M
[INFO] ------------------------------------------------------------------------
In the com.custom.karafhost project, disclose the run_configurations folder and select the appropriate - Run.launch target to start the Karaf session.
Once Karaf has started up, you can enter the Eclipse Console to interact with the running instance. For instance, features:list will list the available features and their installation state. Assuming everything built, the tail of the features:list should include:
…SNIP…
[installed ] [0.0.1-SNAPSHOT ] karafbundle repo-0
[installed ] [0.0.1-SNAPSHOT ] scalabundle repo-0
[installed ] [0.0.1-SNAPSHOT ] karafservlet repo-0
You can also interact with the included WebConsole by visiting the page at http://localhost:8080/system/console. Login using:
- user: karaf
- password: karaf
The HTTP port is configurable in the .../com.custom.karafhost/src/main/resources/karaf/etc/org.ops4j.pax.web.cfg file's org.osgi.service.http.port property.
To shutdown the Karaf instance, enter the shutdown command in the console.
Karaf introduces a packaging abstraction called a Feature. Features are collections of JARs that represent a single application-level set of functionality. The bundles in this repo include the following feature mappings:
- karafbundle -> com.custom.karafbundle
- karafservlet -> com.custom.karafservlet
- scalabundle -> com.custom.scalabundle
The feature mappings are defined in .../com.custom.karafhost/src/main/resources/karaf/system/features.xml
To add your custom feature bundle:
- Create a new project
- Add the new project to the modules section in .../chiller/com.custom.karafhost/pom.xml
- Add the feature group to the .../com.custom.karafhost/src/main/resources/karaf/system/features.xml file. This is where you will define the feature-name, which is used in the next two steps.
- In the add-local-features-to-repo execution id in .../chiller/com.custom.karafhost/pom.xml, include your new feature-name in the list of features to include in the distribution. If you don't deploy your feature-name to the local-repo, it won't be available at runtime.
- If you would like your feature to launch at startup, in .../com.custom.karafhost/src/main/resources/karaf/etc/org.apache.karaf.features.cfg, add your new feature-name to the comma-separated featuresBoot property. Note that specifying a non-existent feature-name to launch at boot time doesn't seem to generate an error.
- Clean and rebuild the parent com.custom.karafhost project. Once the build is launched, use the features:list command to verify that your custom feature is both deployed and installed.
- I'm not sure how to brand the Karaf WebConsole. I tried the Felix approach, but was unsuccessful.
- This was primarily a learning experience for Karaf, so I'd appreciate any corrections or improvements.