ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r829675 - in /websites/staging/ace/trunk/content: ./ user-doc/ace_server_ui.png user-doc/user-guide.html
Date Wed, 22 Aug 2012 10:36:02 GMT
Author: buildbot
Date: Wed Aug 22 10:36:01 2012
New Revision: 829675

Staging update by buildbot for ace

    websites/staging/ace/trunk/content/user-doc/ace_server_ui.png   (with props)
    websites/staging/ace/trunk/content/   (props changed)

Propchange: websites/staging/ace/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Wed Aug 22 10:36:01 2012
@@ -1 +1 @@

Added: websites/staging/ace/trunk/content/user-doc/ace_server_ui.png
Binary file - no diff available.

Propchange: websites/staging/ace/trunk/content/user-doc/ace_server_ui.png
    svn:mime-type = image/png

Added: websites/staging/ace/trunk/content/user-doc/user-guide.html
--- websites/staging/ace/trunk/content/user-doc/user-guide.html (added)
+++ websites/staging/ace/trunk/content/user-doc/user-guide.html Wed Aug 22 10:36:01 2012
@@ -0,0 +1,279 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+  <head>
+    <title>ACE Users guide</title>
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+    <meta property="og:image" content="" />
+    <link rel="stylesheet/less" type="text/css" href="/lib/bootstrap.less">
+    <link href="/css/prettify.css" rel="stylesheet" media="screen">
+    <link href="/css/code.css" rel="stylesheet" media="screen">
+    <script src="/js/less-1.2.1.min.js" type="text/javascript"></script>
+    <script src=""></script>
+    <script src="/js/prettify.js"></script>
+    <script src="/js/bootstrap-alert.js"></script>
+    <script src="/js/bootstrap-dropdown.js"></script>
+    <script src="/js/bootstrap-tooltip.js"></script>
+    <script src="/js/bootstrap-alerts.js"></script>
+    <script src="/js/bootstrap-modal.js"></script>
+    <script src="/js/bootstrap-transition.js"></script>
+    <script src="/js/bootstrap-button.js"></script>
+    <script src="/js/bootstrap-popover.js"></script>
+    <script src="/js/bootstrap-twipsy.js"></script>
+    <script src="/js/bootstrap-buttons.js"></script>
+    <script src="/js/bootstrap-scrollspy.js"></script>
+    <script src="/js/bootstrap-typeahead.js"></script>
+    <script src="/js/bootstrap-carousel.js"></script>
+    <script src="/js/bootstrap-tab.js"></script>
+    <script src="/js/bootstrap-collapse.js"></script>
+    <script src="/js/bootstrap-tabs.js"></script>
+    <script>
+    $(function () { prettyPrint() })
+    $().dropdown()
+    </script>
+  </head>
+  <body style="padding-top: 50px;">
+    <div class="navbar navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="/index.html">Apache ACE&trade;</a>
+          <ul class="nav">
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">News <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/news.html">News</a>
+      </li>
+      <li>
+        <a href="/on-the-web.html">On the web</a>
+      </li>
+    </ul>
+  </li>
+  <li>
+    <a href="/downloads.html">Downloads</a>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">User Documentation <b
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/user-doc/introduction.html">Introduction</a>
+      </li>
+      <li>
+        <a href="/user-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
+        <a href="/user-doc/features.html">Features</a>
+      </li>
+	  <li>
+        <a href="/user-doc/restapi.html">Client REST API</a>
+      </li>
+      <li>
+        <a href="/user-doc/faq.html">FAQ</a>
+      </li>
+      <li>
+        <a href="/user-doc/support.html">Support</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developer Documentation
<b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/dev-doc/getting-started.html">Getting Started</a>
+      </li>
+      <li>
+        <a href="/dev-doc/requirements/">Requirements</a>
+      </li>
+      <li>
+        <a href="/dev-doc/architecture.html">Architecture</a>
+      </li>
+      <li>
+        <a href="/dev-doc/analysis/">Analysis</a>
+      </li>
+      <li>
+        <a href="/dev-doc/design/">Design</a>
+      </li>
+      <li>
+        <a href="/dev-doc/coding-standards.html">Coding Standards</a>
+      </li>
+      <li>
+        <a href="/dev-doc/release-guide.html">Release Guide</a>
+      </li>
+      <li>
+        <a href="/dev-doc/writing-tests.html">Writing unit/integration tests</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Involved <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="/get-involved/mailing-lists.html">Mailing Lists</a>
+      </li>
+      <li>
+        <a href="/get-involved/issue-tracking.html">Issue Tracking</a>
+      </li>
+      <li>
+        <a href="/get-involved/source-code.html">Source Code</a>
+      </li>
+      <li>
+        <a href="/get-involved/project-team.html">Project Team</a>
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Wiki <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="">Board
Reports <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="">Homepage <i
+      </li>
+    </ul>
+  </li>
+  <li class="dropdown">
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a>
+    <ul class="dropdown-menu">
+      <li>
+        <a href="">Apache Homepage <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="">Licenses <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="">Security <i class="icon-share-alt"></i></a>
+      </li>
+      <li>
+        <a href="">Sponsorship <i
+      </li>
+      <li>
+        <a href="">Thanks <i class="icon-share-alt"></i></a>
+      </li>
+    </ul>
+  </li>
+        </div>
+      </div>
+    </div>
+    <div class="container">
+      <p><a href="/"><i class='icon-home'></i> Home</a>&nbsp;&raquo&nbsp;<a
+      <h1>ACE Users guide</h1>
+      <div class="clear"></div>
+      <div id="content"><p>This article describes how to use ACE and should be
a good starting point for new users of Apache ACE. The remainder of this article assumes you've
read and followed the "<a href="/user-doc/getting-started.html">Getting Started</a>"
guide, meaning that you have an ACE server successfully up and running.</p>
+<h2 id="introduction">Introduction</h2>
+<p>Apache ACE is a framework that enables you to provision OSGi software(components)
in a controlled manner. What this means is that you have a central server to which clients,
or "targets" in ACE terminology, connect and fetch their software from. This allows one to
control which target gets which software. </p>
+<p>The software that is deployed to a target, is composed of one or more distributions.
A distribution is roughly similar to a piece of self-contained software. For example, think
of a distribution as C/C++ Development Tooling that you can install on the Eclipse platform.
On its own, distributions consists of one or more features, that provide pieces of functionality
to your software. The difference between a feature and distribution is that the former is
not necessarily fully self-contained: it might need other features in order to work. Each
feature groups one or more artifacts. An artifact is anything from an OSGi bundle, configuration
file or any other kind of artifact that is needed for the software to work. </p>
+<p>The artifacts themselves reside on an <abbr title="OSGi Bundle Repository">OBR</abbr>,
which can be either the default one supplied by ACE, or an external one. Think of an <abbr
title="OSGi Bundle Repository">OBR</abbr> as a kind of Maven repository, storing
read-only versions of artifacts<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>.
As the <abbr title="OSGi Bundle Repository">OBR</abbr> is the single source for
all artifacts, and therefore the software that is deployed on a target, ACE is able to calculate
how to upgrade a target from one version to another version. This is possible because all
changes made to (the metadata of) ACE are stored in an internal versioned database. </p>
+<h2 id="workflow">Workflow</h2>
+<p>The typical use case for using ACE is where you want to control and manage which
software runs on what target. So, how does one use ACE in practice? To explain the typical
workflow of ACE, let's take the following example.<br />
+Assume you are working on a large OSGi-based system that provides some kind of service to
your customers (the exact details on what it does isn't relevant for this example). Since
you're trying to make real money out of it, and take development seriously, you want to set
up a <abbr title="Development, Testing, Acceptance and Production">DTAP</abbr>
environment. Your developers are working on their development machines, using the bleeding
edge software. They are smart guys that can set up their own environments, so ACE won't be
of much help here.<br />
+<p>There is also have a tester on your team, responsible for testing all the new features
and bug fixes made by your developers. This tester does not want to have to set up its own
environment and fiddle around with configuration files and such. Instead, he simply wants
a working test environment that runs a recent version of your software. This is were ACE can
help you out. All you need to do is create a testing target, on which a recent software version
gets deployed. That "recent version", can, for example, be a nightly build that comes out
of your <abbr title="Continuous Integration">CI</abbr> server that automatically
gets pushed to ACE after the nightly build is finished. Alternatively, the tester also can
deploy an older version to its testing target through the ACE server UI, for example, to do
some regression testing.</p>
+<p>Before a new version of your software is put into production, your customers want
to do some acceptance testing to see whether this new version does not break anything. The
acceptance environment should only be updated when a new version is released and after that
remains as-is. In practice, this is most often not the case, as the acceptance environment
is, when not used by any customer, confiscated by your tester for its daily testing purposes,
simply, because ACE allows him to easily deploy other versions to the acceptance environment.
When a customer asks for an acceptance test, he simply deploys the latest greatest official
release to the acceptance environment, and lets the customer do its testing. After that, he
can repurpose it again.</p>
+<p>When all acceptance tests are successful, the new version of your software needs
to be deployed on several production environments, which is done by you, the release manager.
As most production environments only differ in a few details, such as IP addresses and database
credentials, you use the template engine of ACE to make specific configuration files for each
production target. This way, you can easily scale up your production environment by defining
new targets and provide them with the necessary configuration values.</p>
+<h2 id="working-with-ace-server">Working with ACE Server</h2>
+<p>The server UI might look a bit daunting at first, but once you become more familiar
with it, you'll see that it is rather easy to work with.<br />
+After logging in, the main window consists of two main areas:</p>
+<li>The control area at the top of the screen, where you can perform actions like,
retrieving the latest repository changes, revert the changes you've made locally, add new
artifacts, and so on;</li>
+<li>The resource area, consisting of (up to) four columns showing the current artifacts,
features, distributions and targets that are known to ACE.</li>
+<p><img alt="Figure 1: ACE server UI" src="ace_server_ui.png" title="Figure 1: The
server UI of ACE, showing the control area at the top, and the resource area below that."
/><br />
+<h3 id="uploading-artifacts">Uploading artifacts</h3>
+<p>To upload one or more artifacts, you click on the "Add artifact…" button. An
"Add artifact" dialogs opened, showing both the artifacts currently in the <abbr title="OSGi
Bundle Repository">OBR</abbr> and a list of uploaded artifacts. There are two possibilities
to upload a file:</p>
+<li>Upload the individual artifacts by pressing the "Upload" button and selecting the
artifact from the file chooser dialog, or;</li>
+<li>by using drag-and-drop: select all artifacts in an Explorer or Finder and drag
them onto the "Upload artifact" area. This way, you can upload multiple artifacts in one go.</li>
+<p>Once artifacts are uploaded, they appear in the Artifacts listing. For each artifact,
you can edit its properties by double clicking on it. In addition, you can unlink an artifact
from a feature, which will be discussed later on, and remove an artifact. <strong>Note</strong>:
removing an artifact will only remove it from the server's metadata, <em>not</em>
from the <abbr title="OSGi Bundle Repository">OBR</abbr>. </p>
+<p>If you try to upload an artifact that is not recognized by ACE, an error is displayed
noting that that particular artifact is not uploaded. Adding support for particular artifacts
in ACE is discussed in <a href="/dev-doc/adding-artifact-recognizers.html">this article</a>.</p>
+<p><strong>NOTE</strong>: All changes made through the Web UI need to be
stored explicitly by pressing the "Store" button, otherwise they will not be visible to the
ACE server. In case you want to revert all changes, you can use the "Revert" button. This
will ignore all changes and retrieve the latest state from the server. In case there are no
local changes, you can still retrieve the latest state from the server using the "Retrieve"
+<h3 id="creating-a-new-feature-distribution-andor-target">Creating a new feature, distribution
and/or target</h3>
+<p>Adding features and distributions are very similar. You either click the "Add Feature…"
or "Add Distribution…" buttons. In both cases, you are presented with a dialog that allows
you to enter the (mandatory) name of feature (or distribution) and an optional description.
<br />
+There are two ways of adding a target to ACE: either you click the "Add Target…" button
and enter the name of the new target, or let a running target register itself to ACE. The
details on this will be discussed later on.</p>
+<p>After a feature, distribution or target is created, you can edit its properties
by double clicking it. For features and distributions, this means you can alter their description,
while for targets, there are more possibilities to view and alter:</p>
+<li>On the Management tab, you can change whether or not the target should be automatically
updated to the latest software. If selected, all updates will automatically be approved and
distributed to that target. If not, any update must be explicitly approved prior to being
distributed to the target;</li>
+<li>On the Info tab, you can view the current state of the target, such as the currently
installed version, or the latest available software version;</li>
+<li>On the LogViewer tab, you can view the installation log of the target. This allows
you to review the installation of updates on that target;</li>
+<li>The Tag Editor tab allows you to define tags and their replacement values that
will be replaced in any artifacts that contain those tags. This is useful, for example, to
have a single configuration file that can be used for multiple targets. </li>
+<h3 id="creating-associations">Creating associations</h3>
+<p>To link artifacts to features, you simply select the artifact and drag it on top
of the feature to which it should be associated. The same principle also apply to associate
features to distributions and distributions to targets.<br />
+To delete an association once is created, you can click either the left- or the right side
of the association (viz. either the artifact or the feature), and click the "-" on the opposite
side of the association. For example, to delete an association between an feature and distribution,
you can select the feature first, and hit the "-" on the distribution. Alternatively, you
can select the distribution first and hit the "-" on the feature to delete the association.</p>
+<p>Associations can be parameterized, allowing it to be dynamic in what it matches
on left-side and/or right-side of the association. For example, by default an association
between a bundle artifact and a feature will be made to match the <em>latest</em>
version of the bundle. This way, if you upload a new version of a bundle, the feature will
automatically link to that version. While this is certainly handy in many situations, there
are also situations in which you do not always want to link to the latest greatest version
of a bundle. An example might be the bundles that should run on your production environment,
which should only get an update in controlled upgrades, not when you upload a new artifact
to ACE. To disable the "dynamic" associations between, uncheck the "Dynamic Links" option
in the UI <em>before</em> you create the association. This will create an association
that is explicitly bound to the symbolic name and version of a bundle.</p>
+<h2 id="running-a-target">Running a target</h2>
+<p>As mentioned, a target represents a client on which software can be deployed by
ACE. Actually, a target consists of a small OSGi runtime that runs an management agent that
periodically checks with the ACE server whether or not it is has new software for it. In case
new software is available for a target, it will automatically download it and install it.
+<p>ACE provides a fully self-contained management agent, that can be run as plain Java
JAR, named <tt>org.apache.ace.launcher.jar</tt>. This management agent wrapper
accepts the following command line arguments:</p>
+<dd>configures the target to act as multiple management agents: <code>agent-id,identification,discovery[;agent-id,identification,discovery]*</code>;</dd>
+<dd>point to the properties file containing the authentication credentials for a certain
subsystem. Can be either a directory, file or URL;</dd>
+<dd>sets the ACE server to connect to, should be an URL. Defaults to <code>http://localhost:8080</code>;</dd>
+<dt><code>id</code> or <code>identification</code></dt>
+<dd>defines the name to identify the target on in the ACE server. Defaults to <code>defaultTargetID</code>;</dd>
+<dd>adds an additional bundle to be started with this management agent: <code>bundle=my.fully.qualified.BundleActivator</code>;</dd>
+<dd>sets framework options for the OSGi framework to be created. This argument may
be repeated. For example: <code>fwOption=org.osgi.framework.system.packages.extra=sun.misc,</code>.</dd>
+<p>An example on how to run the launcher is:</p>
+<div class="codehilite"><pre><span class="nv">$ </span>java -jar
org.apache.ace.launcher.jar <span class="nv">id</span><span class="o">=</span>MyTarget
<span class="nv">discovery</span><span class="o">=</span>
+Adding additional bundle activator: org.apache.ace.managementagent.Activator
+Started management agent.
+  Target ID    : MyTarget
+  Server       :
+  Sync interval: 2000 ms
+  Unaffected bundles will not be stopped during deployment.
+<p>After the management agent is started, a new target should appear in the ACE server
after you "Retrieve" the latest changes or "Revert" the current changes. If a target is added
this way to the ACE server (instead of adding it through the "Add target…" button), it
initially will be <em>unregistered</em>. This means that no metadata is present
in the ACE server yet and will not be created. To register a target, you can double click
the target to edit its properties. On the "Management" tab, you can select the "Registered?"
(and optionally the "Auto approve?" option as well) and close the dialog by pressing "Ok"<sup
id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup>. </p>
+<h3 id="using-the-template-engine-for-targets">Using the template engine for targets</h3>
+<p>If you want to provision software to multiple targets, those targets probably need
to have their own specific configuration. For example, the IP address on which it should listen
for web requests, or the credentials to access a database. One could create specific configuration
files for each target, however, this can become quite tedious is you have lots of targets.
Aside that, ACE requires that each artifact has an unique name, so you need to create unique
file names for your configuration files for each change you make. Fortunately, ACE provides
an easier way to solve this problem: an template engine.</p>
+<p>All configuration files<sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup>
can be regarded as templates, in which variables are replaced with values supplied by ACE.
In fact, the values are definable per target, distribution, feature or artifact. To define
variables and their replacement values (or "tags") for, for example, a distribution, open
up its properties dialog by double clicking on it, and selecting the "Tag Editor" tab. Each
line in this editor represents a tag. The key of a tag defines that (part of) the variable
name to be replaced in configuration files, and the value of a tag the actual replacement
value. </p>
+<p>For example, consider the following configuration file:</p>
+<div class="codehilite"><pre><span class="nt">&lt;properties&gt;</span>
+  <span class="nt">&lt;key&gt;</span>ipAddress<span class="nt">&lt;/key&gt;</span>
+  <span class="nt">&lt;value&gt;</span>${context.address}<span class="nt">&lt;/value&gt;</span>
+<span class="nt">&lt;/properties&gt;</span>
+<p>The <tt>${context.address}</tt> represent the variable that will be
replaced. The "context." part is mandatory, and everything after that is user definable. Suppose
we want to deploy this configuration file to two targets, "Target1", which is supposed to
listen on address and "Target2", which is supposed to listen on address
To make the configuration file specific for both targets, we simply need to define a tag on
"Target1", like: <code>address</code> -&gt; <code></code>,
and a similar tag on "Target2", like <code>address</code> -&gt; <code></code>.</p>
+<p><strong>NOTE</strong>: In case a configuration file consists of a variable
that cannot be resolved, it will simply not be replaced, but left as-is. This way, you can
still include Velocity-like templates in your distribution without having them garbled by
+<p>ACE will scan all configuration files and replace all known variables as soon as
a new deployment is created. This means that for our example, both "Target1" and "Target2"
will get their own copy of the configuration file with their specific content. ACE also automatically
versions these generated files, to aid downgrading software.</p>
+<div class="footnote">
+<hr />
+<li id="fn:1">
+<p>Once an artifact is uploaded to the <abbr title="OSGi Bundle Repository"><abbr
title="OSGi Bundle Repository"><abbr title="OSGi Bundle Repository">OBR</abbr></abbr></abbr>,
it cannot be modified anymore. This is necessary in order to allow both software upgrades
as downgrades possible.&#160;<a href="#fnref:1" rev="footnote" title="Jump back to
footnote 1 in the text">&#8617;</a></p>
+<li id="fn:2">
+<p>Do not forget to store your changes!&#160;<a href="#fnref:2" rev="footnote"
title="Jump back to footnote 2 in the text">&#8617;</a></p>
+<li id="fn:3">
+<p>In fact any artifact can be considered as an template, but by default ACE only considers
configuration files. &#160;<a href="#fnref:3" rev="footnote" title="Jump back to footnote
3 in the text">&#8617;</a></p>
+      <hr>
+      <footer>
+        <p>Copyright &#169; 2012 <a href="">The Apache
Software Foundation</a>, Licensed under the <a href="">Apache
License, Version 2.0</a>.<br/>Apache ACE, the Apache ACE logo, Apache and the
Apache feather logo are trademarks of The Apache Software Foundation. All other marks mentioned
may be trademarks or registered trademarks of their respective owners.</p>
+      </footer>
+    </div>
+  </body>

View raw message