Introduction
This guide shows the basic functionality of ACE: deploying bundles to a remote OSGi framework running a management agent.
Using ACE to create a remote file installer
Apache Felix FileInstall can be used to automatically 'watch' directories for new bundles and configuration files, which will be processed.
To get roughly the same functionality, but remote, we can use the simplest server target available.
- Build Apache ACE from source
- Start the server from the core/deploy/target/dev-server-filebased directory by launching the run.sh or run.bat file
- Start a gateway from the core/deploy/target/dev-gateway directory by launching the run.sh or run.bat file. The target will show some exceptions relating to auditlog information; that's correct, this server does not support auditlog information.
- Create a version directory (anywhere), should comply with: deploymentpackage version e.g. 1.0.0
- Copy your bundles-to-be-deployed into the 1.0.0 version directory. Suggestion: use core/lib/servicebased.host-1.0.0.jar. Once deployed a UI will popup.
- Next, find the store directory in the server folder
- Create a <gatewayId> directory in the store-dir: in this case configuredGatewayID
- Copy the entire version directory, 1.0.0 with the containing jar into configuredGatewayID
- Optionally check the available version with your browser, see http://cwiki.apache.org/confluence/display/ACE/Communication+Gateway+and+Server
- That's it! Notice the gateway has started your bundle.
To update a target, add directories with higher version numbers. In these version directories, drop any bundles you want to have provisioned. That's it! Remember that any version you create will be installed at most once: if you create a version directory, and then start adding files to it, you run the risk that your empty folder will get installed, and all additional bundles will be removed from the target. It's easiest to create the version folder somewhere else on your system, and move it to the target's directory when you're done.
Slightly advanced
- To use a 'real' remote server, you can edit the target's configuration. Edit conf/org.apache.ace.discovery.property.cfg to contain your server IP (or name). Remember that, when using multiple targets, each target should have its own name. This can be found in conf/org.apache.ace.identification.property.cfg.
How does this work?
Simply speaking, the target will poll for updated versions, and the server will create a deployment package based on the contents of the file system.
The (configurable) scheduler will, by default, check every two seconds for an update. It does so by connecting to the server it finds in conf/org.apache.ace.discovery.property.cfg, on the endpoint /deployment. It first checks whether there are new versions by looking up /deployment/<gatewayID> (you can try this all in a browser, by the way). If there is a newer version than the one already installed, it will request the newest version, stating its own version.
The server receives the requests for either a list of versions, or a deployment package for some version, and passes it on to the resident deployment provider (in this case, a FileBasedProvider). This will check the file system, and inform the StreamGenerator of the deployment package to be generated. The StreamGenerator will generate a fixpackage (see OSGi compendium, 114.3.3). This will then be returned to the target.
The target will receive the stream, and pass it on to its DeploymentAdmin, which will take care of installing the package.