ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r1376068 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Date Wed, 22 Aug 2012 14:18:24 GMT
Author: marrs
Date: Wed Aug 22 14:18:24 2012
New Revision: 1376068

URL: http://svn.apache.org/viewvc?rev=1376068&view=rev
Log:
Reviewed this guide and added some additional information.

Modified:
    ace/site/trunk/content/user-doc/user-guide.mdtext

Modified: ace/site/trunk/content/user-doc/user-guide.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/user-guide.mdtext?rev=1376068&r1=1376067&r2=1376068&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/user-guide.mdtext (original)
+++ ace/site/trunk/content/user-doc/user-guide.mdtext Wed Aug 22 14:18:24 2012
@@ -1,34 +1,35 @@
 Title: ACE Users guide
 
-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 "[Getting Started](/user-doc/getting-started.html)"
guide, meaning that you have an ACE server successfully up and running.
-
-Revision 0.8, last updated: August 22nd, 2012.
+This article describes how to use ACE and is a good starting point for new users of Apache
ACE. The remainder of this article assumes you've read and followed the "[Getting Started](/user-doc/getting-started.html)"
guide, meaning that you have an ACE server successfully up and running.
 
 [TOC]
 
-
 ## Introduction
 
 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. 
 
-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. 
-
-The artifacts themselves reside on an OBR, which can be either the default one supplied by
ACE, or an external one. Think of an OBR as a kind of Maven repository, storing read-only
versions of artifacts[^1]. As the OBR 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. 
+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, it could be a plugin
or even a full application. On their own, distributions consist 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 to a configuration file or any other kind of artifact that is needed for the software
to work.
 
+The artifacts themselves reside in an OBR, which can be either the default one supplied by
ACE, or an external one. Think of an OBR as a repository, like the Maven repository or a content
repository, storing immutable versions of artifacts[^1]. As the OBR 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. In other
words, we always keep a full history and audit trail.
 
 ## Workflow
 
-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.  
-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 DTAP 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.  
+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.
+
+Assume you are working on a large OSGi-based system that provides some kind of service to
your users (the exact details on what it does isn't relevant for this example).
 
-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 CI 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.
+Since you're a professional and take development seriously, you want to set up a DTAP environment.

+Your developers are working on their development machines, using the bleeding edge software.
+Even though they are smart guys that know the software inside out and can set up their own
environments, they still might want to use ACE on their local machines to validate that changes
they make indeed work when deployed. In this cases it makes sense to use the same deployment
method that is used in production lateron as well.
 
-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.
+There is also 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 his 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 targets for testing, on which a recent software version gets
deployed. That "recent version", can, for example, be a nightly build that comes out of your
CI server that automatically gets pushed to ACE after the nightly build is finished. Alternatively,
the tester also can deploy an older version to his testing target through the ACE server UI,
for example, to do some regression testing. A third scenario might be to duplicate the exact
configuration and version that is currently deployed to a specific user's target.
+
+Before a new version of your software is put into production, your users want to do 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 user,
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 user asks for an acceptance
test, he simply deploys the latest greatest official release to the acceptance environment,
and lets the user do its testing. After that, he can repurpose it again. Another scenario
obviously is that users setup dedicated targets for the purpose of acceptance testing.
 
 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.
 
 
-## Working with ACE Server
+## Working with the ACE Server
 
 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.  
 
@@ -37,66 +38,68 @@ The server UI might look a bit daunting 
 
 After logging in, the main window consists of two main areas:
 
-1. 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;
-2. The resource area, consisting of (up to) four columns showing the current artifacts, features,
distributions and targets that are known to ACE.
-
+1. 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;
+2. The resource area, consisting of (up to) four columns showing the current artifacts, features,
distributions and targets that are known to ACE. When you select an entity here, the associated
entities in other columns will automatically be highlighted, giving you an instant overview
of the links within the system.
 
 ### Uploading artifacts
 
-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 OBR and a list of uploaded artifacts.
There are two possibilities to upload a file:
+To upload one or more artifacts, you click on the "Add artifact…" button. An "Add artifact"
dialog opens, showing both the artifacts currently in the OBR but not in the artifact list
and a list of uploaded artifacts. There are two possibilities to upload a file:
 
 1. Upload the individual artifacts by pressing the "Upload" button and selecting the artifact
from the file chooser dialog, or;
 2. 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.
 
-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. **Note**: removing
an artifact will only remove it from the server's metadata, *not* from the OBR. 
+Once artifacts are uploaded, they appear in the Artifacts column. 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. **Note**: removing
an artifact will only remove it from the server's metadata, *not* from the OBR. 
 
-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 [this article](/dev-doc/adding-artifact-recognizers.html).
+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 new types of artifacts in
ACE is discussed in [this article](/dev-doc/adding-artifact-recognizers.html).
 
 **NOTE**: 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" button.
 
 ### Creating a new feature, distribution and/or target
 
-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.
  
-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.
+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 the feature or distribution and an optional description.
+
+There are two ways of adding a target to ACE:
+
+1. You can pre-register a target by clicking the "Add Target…" button and entering the
name of the new target. This allows you to associate software to this target even before it
has ever been started or seen by the server.
+2. You can register a target that is already running and has already tried to fetch software
from the ACE server. The details on this will be discussed later on.
 
 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:
 
 * 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;
 * 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;
 * 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;
-* 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. 
+* The Tag Editor tab allows you to define tags and their values. Tags can be used for many
things, but one of their more interesting use cases is that they can be used to replace variables
in template artifacts that contain those tags. This is useful, for example, to have a single
configuration file that can be used for multiple targets, because it is largely the same for
all of them.
 
 ### Creating associations
 
-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.  
-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.
-
-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 *latest* 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 *before* you create the association.
This will create an association that is explicitly bound to the symbolic name and version
of a bundle.
+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 applies if you want to associate
features to distributions and distributions to targets.
+To delete an association once is created, you can click either the left- or the right hand
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.
 
+Associations can be parameterized, allowing them to be dynamic in what they match on the
left hand side and/or the right hand side of the association. For example, by default an association
between a bundle artifact and a feature will be made to match the *latest* 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 *before* you
create the association. This will create an association that is explicitly bound to the symbolic
name and version of a bundle.
 
 ## Running a target
 
-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. 
+As mentioned, a target represents a client on which software can be deployed by ACE. Actually,
a target consists of an OSGi runtime that runs a management agent that periodically checks
with the ACE server whether or not it has new software for it. In case new software is available
for a target, it can automatically download and install it.
 
-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:
+ACE provides a fully self-contained target that includes a management agent and can be run
as plain Java JAR, named <tt>org.apache.ace.launcher.jar</tt>. This target accepts
the following command line arguments:
 
 `agents`
-: configures the target to act as multiple management agents: `agent-id,identification,discovery[;agent-id,identification,discovery]*`;
+: Configures the target to have multiple management agents: `agent-id,identification,discovery[;agent-id,identification,discovery]*`.
If you specify this option, the identification and discovery arguments below are ignored.
Configuring multiple management agents is a very specific use case that should be avoided
unless you know exactly what you're doing. It was added so a target can fetch different, non-overlapping
parts of the software from different servers. In general though, it is preferable and more
convenient to channel all software updates through a single server.
 
 `auth`
 : point to the properties file containing the authentication credentials for a certain subsystem.
Can be either a directory, file or URL;
 
 `discovery`
-: sets the ACE server to connect to, should be an URL. Defaults to `http://localhost:8080`;
+: Sets the ACE server to connect to, should be an URL. Defaults to `http://localhost:8080`.
 
 `id` or `identification`
-: defines the name to identify the target on in the ACE server. Defaults to `defaultTargetID`;
+: Defines the name to identify the target on in the ACE server. Defaults to `defaultTargetID`.
 
 `bundle`
-: adds an additional bundle to be started with this management agent: `bundle=my.fully.qualified.BundleActivator`;
+: Adds an additional bundle to be started with this management agent. The bundle itself has
to be on the Java classpath. `bundle=my.fully.qualified.BundleActivator`;
 
 `fwOption`
-: sets framework options for the OSGi framework to be created. This argument may be repeated.
For example: `fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management`.
+: Sets framework options for the OSGi framework to be created. This argument may be repeated.
For example: `fwOption=org.osgi.framework.system.packages.extra=sun.misc,com.sun.management`.
 
 An example on how to run the launcher is:
 
@@ -113,9 +116,9 @@ After the management agent is started, a
 
 ### Using the template engine for targets
 
-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.
+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 if you have lots of targets.
Besides that, ACE requires that each artifact has a 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: a template engine.
 
-All configuration files[^3] 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. 
+All configuration files[^3] 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 and ACE will collect all tags of entities that are associated with a specific
target. 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. 
 
 For example, consider the following configuration file:
 
@@ -127,19 +130,24 @@ For example, consider the following conf
 
 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 192.168.2.1 and "Target2", which is supposed to listen on address 192.168.2.2.
To make the configuration file specific for both targets, we simply need to define a tag on
"Target1", like: `address` -> `192.168.2.1`, and a similar tag on "Target2", like `address`
-> `192.168.2.2`.
 
-**NOTE**: 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 ACE.
+Under the covers, ACE uses Velocity[^4] to parse the template. This means that, apart from
variable substitution, you can also use other Velocity macros and create more complex configurations
that might contain conditional sections, loops and other features Velocity provides.
 
-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.
+**NOTE**: In case a configuration file consists of a variable that cannot be resolved, it
will simply not be replaced, but left as-is.
 
 
+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.
 
 
-[^1]: Once an artifact is uploaded to the OBR, it cannot be modified anymore. This is necessary
in order to allow both software upgrades as downgrades possible.
+
+[^1]: Once an artifact is uploaded to the OBR, it cannot be modified anymore. This is necessary
in order to allow both software upgrades as downgrades and to ensure that everything you do
is reproducible. One thing to note is that this is not compatible with the way that Maven
handles snapshot versions. A snapshot can contain anything. In stead we usually use the version
qualifier to append a timestamp in such scenarios.
 
 [^2]: Do not forget to store your changes!
 
 [^3]: In fact any artifact can be considered as an template, but by default ACE only considers
configuration files. 
 
+[^4]: Apache Velocity is an engine that can generate documents by combining a template with
a context that contains variables. To learn more about it, visit the [Velocity website](http://velocity.apache.org/).
+
+
 
 *[OBR]: OSGi Bundle Repository
 



Mime
View raw message