Apache ACE™

Home » Docs

Getting Started in 5 minutes

This guide shows the core functionality of Apache ACE, organising bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface.

Introduction

Apache ACE consists of several parts:

  1. one or more targets, which essentially is a small OSGi framework containing an ACE agent that contacts the ACE server on a regular basis to inquire for new software that needs to be deployed;
  2. the ACE (provisioning) server, which runs the logic to determine what software needs to be provisioned to what target;
  3. a bundle repository, that contains the actual artifacts that need to be deployed onto the targets;
  4. the ACE client, used to define the what software should be provisioned on which target. By default, there are three different implementations available: a. a web-based client, that provides you a simple drag-and-drop interface to manage your targets; b. a Gogo-shell based client, that allows you to control your targets using the Gogo-shell from Apache Felix; b. a REST-based client, that can be used, for example, to integrate Apache ACE in any other (scripting) language you want.

All of the various parts can either run on a single machine, for demo/testing purposes, or run on various machines, depending on your actual use-case. It is not uncommon that the various parts all run on different machines. In fact, it is one of the easiest ways to scale an Apache ACE instance.

Download the distribution

In order to get started with Apache ACE, you must first download the latest ACE distribution:

  1. Download the latest binary distribution called apache-ace-<version>-bin.zip from the download page;
  2. Unpack the downloaded archive somewhere on your filesystem.

Start the ACE server

As explained above, Apache ACE consists of several different parts. For convenience, the ACE distribution provides an all-in-one variant that allows you to start the ACE provisioning server, a bundle repository and the ACE web-based client using a single JAR:

  1. Open a terminal and navigate to the root of the distribution;
  2. Navigate to the sub directory server-allinone;
  3. Start the server using java -jar server-allinone.jar.

In case you are wondering how you can tweak Apache ACE, there are some properties that can be overridden directly from the command line (for convenience), but most of the configuration options are defined in the configuration files located in the conf directory inside the server-allinone directory. For example, to start the web server of Apache ACE on a different port, you can start the server as follows:

java -Dorg.osgi.service.http.port=9000 \
     -Dorg.apache.ace.server=localhost:9000 \
     -Dorg.apache.ace.obr=localhost:9000 \
     -jar server-allinone.jar

Since you're moving all the different parts to a different port, that is, the provisioning server and bundle repository, to a different port, you need to redefine a couple of properties in order to make this work.

To test your server is up and running, you can go to http://localhost:8080/ace (or http://localhost:9000/ace in case you're using a different port) to be presented with the a login dialog. You can login by using the default credentials which is d as username and f as password.

Start an ACE target

Now we have the ACE server up and running, we can start an actual target to deploy software to. To start a single target, you need to:

  1. Open a terminal and navigate into the root of the ACE distribution;
  2. Navigate to the sub directory target;
  3. Start the target using java -jar target.jar.

Similar as with the ACE server, you can tweak the configuration of the target from the commandline. For example, if you changed the default port of the ACE server to 9000, you need to run the following command:

java -Dagent.discovery.serverurls=http://localhost:9000 \
     -jar target.jar

A more comprehensive list of paramaters you can override is described in the user guide.

Provisioning software

The basic workflow for defining what software needs to be provisioned to what target is:

  1. you start with checking out a workspace, in the web UI, this is done implicitly for you once you start to interact with the user interface;
  2. you add the artifacts and define the feature(s) and distribution(s) that need to be deployed onto your targets;
  3. once you're satisfied with the results, you can commit the results back to the ACE server, at which point they will be applied to your targets.

For this demonstration, you need a couple of bundles that you can deploy onto a target. In case you do not have any bundles "lying around", you can take a look at the sample application as provided by the Apache Felix project. Follow its instructions and once you're able to run the application locally, you can use the resulting bundles in ACE.

  1. Go to the ACE web-based UI, and click Retrieve in order to be sure that you have the latest version of the repository. If your target is up and running, it should be displayed in the "Targets" column with a name of target-1;
  2. Add the artifacts you want to deploy. This can be done in two ways: either by dragging-and-dropping them directly onto the "Actifacts" column (a blue border or line should appear for the artifacts to be accepted). Alternatively, you can use the + button above the "Artifacts" column and using the "Upload" button in the dialog presented for each artifact you want to add;
  3. Create a new feature by clicking on the + button above the Features column, give it a name and acknowledge the dialog;
  4. Create a distribution by clicking on the + button above the "Distributions" column, again give it a name and acknowledge the dialog;
  5. Next, you can create associations between your artifacts, features, distributions and targets: a. select one or more artifacts and drag them onto the feature you created. This will associate these artifacts to your feature; b. select your feature and drag it onto your distribution, creating an association between your feature and distribution; c. select your distribution and drag it onto your target to associate your distribution to your target.
  6. Verify your associations are correct by clicking your artifacts, features and distributions. Doing this should highlight the associations. To persist the changes, you can use the Store button at the top of the screen;
  7. After a couple of seconds, the software is deployed onto the target. If you used the Felix demonstration application, you should be presented with a nice Swing UI.

It doesn't work!

If the previous steps did not provided you with a Swing UI, you need to find out what went wrong. There are several ways to find out why your target is not being provisioned correctly:

  1. Inspect state and log of the target by double-clicking it in the web UI. It presents you a dialog with a couple of tabs. On the Info tab, you can find some basic information on the actual state of the target, such as which version is deployed, which version should be deployed, and so on. Alternatively, the LogViewer provides you a little more information on what might be wrong. It is a very basic view on the log entries that the target sent back to the server;
  2. Alternatively, you can go to the terminal where your target is running and use the Gogo shell to find out what is happening directly onto the target. You can use log 1 to see the latest log entries, or lb to list the bundles that are currently running. Most of the times, the log gives you some clue what went wrong.

Next steps

If you want to continue on learning more details on Apache ACE, you can continue to the detailed user guide. Or you might want to go back to the main documentation to check out any other topic that might be of interest.