Apache Karaf: a modulith runtime you operate from a shell

A runtime designed to be operated, not just started

Apache Karaf describes itself as a modulith runtime supporting several frameworks and programming models, REST and API, web, Spring Boot among them. The framing in the README is that it provides turnkey features you can use directly, packaged as a mutable or an immutable application.

That distinction between mutable and immutable packaging is the design decision that explains the whole product. In a mutable setup the runtime is a live system that an operator reconfigures and reconfigures, and in an immutable one the application is assembled ahead of time and deployed as a unit. The mutable path is the unusual one, and it is the reason the feature list reads like an operations manual.

Almost every item in that list is about change after start up. There is hot deployment of applications in the deploy directory, a central etc directory holding configuration in properties or JSON that can be plugged onto an existing configuration backend, provisioning of libraries and applications that are downloaded, installed and started, an extensible text console for managing services and their state, and commands for creating, deleting, starting and stopping Karaf instances.

The audience, then, is a platform or operations team that wants an application platform it can reconfigure in production without a full redeploy, and the developers of frameworks that want to ship on top of such a runtime.

The etc directory and the deploy directory are the control surface

Karaf's dynamic configuration is built around one directory. The README describes it as a central location, the etc directory, holding configuration in different formats, properties and JSON, and says it can be plugged onto an existing configuration backend. That last point matters more than it first appears, because a runtime whose configuration lives in files on disk is a runtime that needs a strategy for how those files reach the machine.

Hot deployment works the same way, with applications dropped into the deploy directory. The behaviour you get from that is the interesting part: the runtime picks the artefact up and makes it part of the running system, and because the same directory holds the configuration, a change to configuration and a change to code follow the same operational path.

The trade is that you give up the guarantee that a running process matches a known artefact. A mutable runtime can be in a state that nobody wrote down, and recovering that state means understanding what was dropped in when. Karaf answers this with commands that let you inspect and manage services, and with the instance management commands that create, delete, start and stop Karaf instances from the console, so the operational workflow is at least scriptable.

For teams with immutable infrastructure, that flexibility is dead weight. Karaf keeps the option open, since the same runtime packages as an immutable application, but the tooling is aimed at the mutable case.

Provisioning pulls bundles in and the resolver works out the rest

Provisioning is the feature that makes Karaf different from a servlet container with extra steps. The README describes it as provisioning of libraries or applications through a number of different ways, by which they are downloaded locally, installed and started, and it states that provisioning interacts with the resolver to automatically install the required components.

The resolver is the important half. When you provision a single artefact, the runtime works out the transitive set of what it needs and brings that in as well. The user asks for one thing and gets a resolved dependency set, which is what an OSGi style runtime can do and what a classpath oriented container generally cannot do at runtime.

The trade-off is that resolution is a moving target. A resolved set assembled on a machine at a moment in time is not the same as a dependency set pinned in a build file, and if the resolver can pick versions at runtime, the artefact you deploy is not fully determined by what you shipped. The examples directory includes bundle, deployer and config examples, which tells you the provisioning and resolution behaviour is worth reading before you depend on it.

Logging follows the same philosophy of a centralised back end. Karaf uses a Log4J based logging back end and exposes it through a number of APIs, listed in the README as JDK 1.4, JCL, SLF4J, Avalon and Tomcat, so applications using any of those logging facades end up in one place.

The console, SSH and JAAS are one coherent design

The shell is the centre of the product. The README calls it a nice text console where you can manage the services, install new applications or libraries and manage their state, and it is extensible by deploying new commands dynamically along with new features or applications. That last point is the same philosophy as hot deployment applied to the operator interface: a command can be added to a running system without restarting it.

Remote access follows directly. You use any SSH client to connect to the kernel and issue commands in the console, so the same interface used locally on the machine is used from a laptop. Security is handled by a JAAS based security and access control framework providing a complete RBAC solution, which means who may run which command in the console is a policy question rather than something bolted on at the SSH layer.

The repository layout backs this up. There are dedicated jaas, shell, client, instance, deployer, features and config modules, alongside the log, management, diagnostic, event and scr directories, and the webconsole directory for the browser based console. A diagnostic module in particular suggests the runtime can describe its own state, which is what you need when an operator has to answer why a bundle did not resolve.

The examples directory mirrors the feature set with dedicated projects for the command, jaas, config, deployer, instance, blueprint and dump use cases, so the console model can be studied through working code rather than only through the manual.

A services catalogue: JDBC, JPA, JTA, JMS, HTTP and CXF

Karaf ships what an enterprise Java application tends to need, and the README lists the enterprise features as JDBC, JPA, JTA and JMS, with a full featured HTTP service providing a web container for deploying web applications, and REST and service support through different service frameworks such as Apache CXF.

Two of those deserve a note. The HTTP service means web applications are deployed into a container inside the runtime, which is a heavier arrangement than putting a jar next to a standalone server. The CXF integration is the bridge to the wider service framework world, and it is the reason service oriented modules in the ecosystem tend to assume Karaf rather than a bare JVM.

Karaf is also a supported runtime for other projects, with Apache Camel named in the README, and the runtime can be extended by other Karaf subprojects such as Karaf Decanter, Karaf Cellar and Karaf Cave. The examples directory reflects that ecosystem, with a Camel example, a Blueprint example, a servlet example, a REST example, a GraphQL example, a scheduler example, a Redis example and a JDBC example, among others.

The consequence for an adopter is that the surface area is large. Every one of those services is another subsystem with its own configuration in the etc directory, and each one is a candidate for the kind of problem that only shows up when a system is running rather than when it is being built.

A 4.4.x line, a PDF manual and a note about Windows unzip tools

The maintenance picture is a mature one. The recent releases are karaf-4.4.12 on 2026-09-22, karaf-4.4.11 on 2026-04-27 and karaf-4.4.10 on 2026-02-13, and the last push to the repository was on 2026-10-20, so the branch is active and the patch line is still moving. The repository is not archived, and it is under the Apache License 2.0 with the ASF NOTICE file and the usual licence header, so the licence position is the standard permissive one with the patent grant and the notice requirement.

The documentation is the weak spot in the README's own telling. For a source distribution it points you at BUILDING.md, it says the PDF manual is the right place to find any information about Karaf, and it points at the examples directory for turnkey minimal applications you can deploy and extend or template. A separate documentation page, a news page and a download page are linked, and the repository carries a manual directory as well.

The one practical note in the getting started section is about unpacking. Windows users are told to use 7zip or another unzip tool to support files longer than 255 characters, which is the kind of detail that only appears once someone has hit it.

For contributors, the project points at the user and developer mailing lists, GitHub issues, and a contributor's guide, and the tree includes .gitpod.yml, docker, archetypes, assemblies, a bom directory and itests for integration tests.

Editorial conclusion

Adopt Apache Karaf when you need a runtime where applications and libraries can be installed, started and stopped after the JVM is already running, and where operators work from a console over SSH rather than from a deployment pipeline. Do not adopt it when you want a small embedded library or a container you never touch at runtime, because the feature list alone, from provisioning to instance management, assumes an operator in the loop. Verify first that the subsystem you need is in a release you can actually obtain, that the examples in the repository cover the framework you intend to use, and that your platform can unpack the distribution, since the README warns Windows users to use 7zip for files longer than 255 characters.

Frequently asked questions

Official sources

1. apache/karaf on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases