Author: jawi
Date: Thu Nov 7 14:45:59 2013
New Revision: 1539668
URL: http://svn.apache.org/r1539668
Log:
ACE-251: update user guide:
- to include documentation about using the template engine
(which was already documentated in some form);
- updated the documentation to reflect the latest changes
in the UI and the new agent;
- added more images showing some of the functionality.
Added:
ace/site/trunk/content/user-doc/ace_dnd_artifacts.png (with props)
ace/site/trunk/content/user-doc/ace_dnd_artifacts_fail.png (with props)
ace/site/trunk/content/user-doc/ace_dnd_artifacts_ok.png (with props)
ace/site/trunk/content/user-doc/ace_dynamic_association.png (with props)
ace/site/trunk/content/user-doc/ace_static_association.png (with props)
ace/site/trunk/content/user-doc/ace_target_tag_editor.png (with props)
Modified:
ace/site/trunk/content/user-doc/ace_server_ui.png
ace/site/trunk/content/user-doc/user-guide.mdtext
Added: ace/site/trunk/content/user-doc/ace_dnd_artifacts.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_dnd_artifacts.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_dnd_artifacts.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/user-doc/ace_dnd_artifacts_fail.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_dnd_artifacts_fail.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_dnd_artifacts_fail.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/user-doc/ace_dnd_artifacts_ok.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_dnd_artifacts_ok.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_dnd_artifacts_ok.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/user-doc/ace_dynamic_association.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_dynamic_association.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_dynamic_association.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Modified: ace/site/trunk/content/user-doc/ace_server_ui.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_server_ui.png?rev=1539668&r1=1539667&r2=1539668&view=diff
==============================================================================
Binary files - no diff available.
Added: ace/site/trunk/content/user-doc/ace_static_association.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_static_association.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_static_association.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: ace/site/trunk/content/user-doc/ace_target_tag_editor.png
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/ace_target_tag_editor.png?rev=1539668&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ace/site/trunk/content/user-doc/ace_target_tag_editor.png
------------------------------------------------------------------------------
svn:mime-type = image/png
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=1539668&r1=1539667&r2=1539668&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/user-guide.mdtext (original)
+++ ace/site/trunk/content/user-doc/user-guide.mdtext Thu Nov 7 14:45:59 2013
@@ -8,9 +8,10 @@ This article describes how to use ACE an
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, 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 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
+operate properly. 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.
+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, ACE always keeps a full history and audit trail for
all changes.
## Workflow
@@ -43,20 +44,32 @@ After logging in, the main window consis
### Uploading artifacts
-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:
+The easiest way to add one or more *new* artifacts is by simply dragging and
dropping them on the artifact column. *Note that a drop is accepted only when a
blue line or border is shown around the artifacts column (see figure 2)*. The
artifacts are uploaded automatically in the background, and when they are
complete, a summary of the upload results is shown as notification (see figure
3).
-1. Upload the individual artifacts by pressing the "Upload" button and
selecting the artifact from the file chooser dialog, or;
+<a href="ace_dnd_artifacts.png" target="_blank"><img
src="ace_dnd_artifacts.png" width="640px" title="Figure 2: Adding new artifacts
by dragging them onto the artifacts column. Note the blue line surrounding the
artifacts column denoting the drop can be accepted." /></a>
+**Figure 2**: Adding new artifacts by dragging them onto the artifacts column.
Note the blue line surrounding the artifacts column denoting the drop can be
accepted (click on image to see full size).
+
+<a href="ace_dnd_artifacts_ok.png" target="_blank"><img
src="ace_dnd_artifacts_ok.png" width="640px" title="Figure 3: A notification is
shown when all artifacts are successfully uploaded." /></a>
+**Figure 3**: A notification is shown when all artifacts are successfully
uploaded (click on image to see full size).
+
+To add artifacts that are already in the OBR, you click the "Add artifactâ¦"
button. An "Add artifact" dialog opens, showing the artifacts currently in the
OBR (but not yet in the list of selected artifacts) and a list of
to-be-uploaded artifacts. This window also allows you to upload artifacts, and
offers two options to do so:
+
+1. by uploading 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 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, a failure
notification is displayed noting that that particular artifact is not uploaded,
see also figure 4. Adding support for new types of artifacts in ACE is
discussed in [this article](/dev-doc/adding-custom-artifact-types.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-custom-artifact-types.html).
+<img src="ace_dnd_artifacts_fail.png" width="369px" title="Figure 4: A failure
notification is shown when one or more artifacts could not be recognized by
ACE." />
+**Figure 4**: A failure notification is shown when one or more artifacts could
not be recognized by ACE.
-**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.
+Once all artifacts are uploaded, they appear as selected rows in the artifacts
column. You can immediately drag them onto the feature column to link them to a
particular feature. By double clicking on an artifact, you can edit some of its
properties, for example, its description.
+To remove an artifact from the artifacts column, you simply press its
trash-can icon. Note that removing an artifact will only remove it from the
artifacts column, *not* from the OBR.
+
+**NOTE**: All changes made through the Web UI need to be stored explicitly by
pressing the "Store" button or by hitting CTRL+S (or CMD+S if you happen to use
OSX), otherwise they will not be visible to the ACE server. In case you want to
revert all changes, you can use the "Revert" button or CTRL/CMD+U. This will
ignore all local changes but does *not* retrieve the latest state from the
server. To retrieve the latest state from the server, use the "Retrieve" button
or CTRL/CMD+G.
### 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 the feature or
distribution and an optional description.
+Adding features and distributions are very similar. You either click the "Add
Featureâ¦" or "Add Distributionâ¦" buttons (or use the shortcut keys
CTRL/CMD+F and CTRL/CMD+D). 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:
@@ -73,79 +86,122 @@ After a feature, distribution or target
### 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
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.
+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 "broken chain" button 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 "broken chain"
button on the distribution. Alternatively, you can select the distribution
first and hit the "broken chain" button on the feature to delete the
association.
+
+There is a subtle, but very important, difference when you associate a
bundle-artifact to a feature by dragging its symbolic name (without a version)
onto a feature, or when you drag a bundle-artifact with a version onto a
feature. In the first case, you make a "dynamic" association (see figure 5),
which states that you always want the *latest* version of that bundle to be
associated to the feature, including any newer version that might be uploaded
in the future. In the latter case, you make a "static" association (see figure
6), which states that you always want that particular version of that bundle to
be associated to the feature.
+
+<img src="ace_dynamic_association.png" width="516px" title="Figure 5: Creating
a dynamic association by dragging the BSN of a bundle onto a feature." />
+**Figure 5**: Creating a dynamic association by dragging the BSN of a bundle
onto a feature.
-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.
+<img src="ace_static_association.png" width="522px" title="Figure 6: Creating
a static association by dragging a particular version of a bundle onto a
feature." />
+**Figure 6**: Creating a static association by dragging a particular version
of a bundle onto a feature.
+
+Creating dynamic associations is currently only supported for bundle
artifacts. For other types of artifacts, such as configuration files, only
static associations can be created[^2].
## Running a target
-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.
+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 at least the
ACE management agent. This management agent periodically checks with the ACE
server whether or not new software is available. In case new software is
available for a target, it can automatically download and install it.
+
+ACE provides a runnable eclipse project, <tt>run-target</tt> that starts an
OSGi runtime, the ACE management agent, and a Gogo shell for easy debugging and
demo purposes. The management agent, or agent for short, itself can be found in
the <tt>org.apache.ace.agent</tt> project. This agent simply does the following:
+
+1. it uploads the audit log of the target to the ACE server. The audit log
contains all changes in bundle and framework state, such as the starting and
stopping of the framework and (de)installation of bundles;
+2. it check whether or not software updates are available. If so, it will
download it and install this update automatically.
+
+The agent can be configured by supplying it options through the command line
(e.g. <tt>-Dname=value</tt>):
+
+<tt>agent.identification.agentid</tt>
+: defines the name to uniquely identify a target on the ACE server. In case
this option is not supplied, a default value of `defaultTargetID` is used;
-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:
+<tt>agent.discovery.serverurls</tt>
+: defines the ACE server URLs to connect to. Multiple URLs can be given to get
a form of fail-over: in case a connection to the first URL cannot be
established, the second URL will be used, and so on. If this option is given,
at least one URL should be supplied, and multiple URLs can be supplied by
separating them with a comma. If this option is omitted, a default value of
<tt>http://localhost:8080</tt> is used;
-`agents`
-: 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.
+<tt>agent.logging.level</tt>
+: defines the log level of the agent, and should be one of the following
values: <tt>DEBUG</tt>, <tt>INFO</tt>, <tt>WARNING</tt> or <tt>ERROR</tt>. The
default log level is <tt>INFO</tt>;
-`auth`
-: point to the properties file containing the authentication credentials for a
certain subsystem. Can be either a directory, file or URL;
+<tt>agent.controller.syncinterval</tt>
+: defines the interval (in seconds) in which the agent should synchronize with
the ACE server. A default of 60 seconds is used in case this option is not
supplied;
-`discovery`
-: Sets the ACE server to connect to, should be an URL. Defaults to
`http://localhost:8080`.
+<tt>agent.controller.syncdelay</tt>
+: defines how long the agent should wait (in seconds) after startup before it
will synchronize with the ACE server for the first time. A default of 5 seconds
is used in case this option is not supplied;
-`id` or `identification`
-: Defines the name to identify the target on in the ACE server. Defaults to
`defaultTargetID`.
+<tt>agent.controller.streaming</tt>
+: if given a value of <tt>false</tt>, all software updates will be downloaded
completely first after which it will be installed. Use this value in case you
suffer from unreliable network connections. A value of <tt>true</tt> (the
default) causes the agent to download and install any software update directly.
-`bundle`
-: 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`;
+<tt>agent.controller.fixpackages</tt>
+: if given a value of <tt>true</tt> (the default), software updates will only
contain the deltas or changed artifacts. For large deployment packages, this
can dramatically reduce the size of an update. Use a value of <tt>false</tt> to
get all artifacts for each software update;
-`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`.
+<tt>agent.controller.retries</tt>
+: defines the number of times the agent should retry to install a software
update in case its installation fails. If omitted, an installation is retried 3
times;
-An example on how to run the launcher is:
+<tt>agent.connection.authtype</tt>
+: defines how to connections to the server are to be authenticated. Valid
values are <tt>NONE</tt> for no authentication, <tt>BASIC</tt> for using
HTTP-BASIC authentication or <tt>CLIENTCERT</tt> for using client certificates.
In case this option is omitted, a value of <tt>NONE</tt> is assumed and no
authentication is used. In case of the values <tt>BASIC</tt> or
<tt>CLIENTCERT</tt>, additional options should be supplied (see below);
- :::sh
- $ java -jar org.apache.ace.launcher.jar id=MyTarget
discovery=http://192.168.1.1:8080
- Adding additional bundle activator:
org.apache.ace.managementagent.Activator
- Started management agent.
- Target ID : MyTarget
- Server : http://192.168.1.1:8080
- Sync interval: 2000 ms
- Unaffected bundles will not be stopped during deployment.
+<tt>agent.connection.username</tt> and <tt>agent.connection.password</tt>
+: provide the username and password used for HTTP-BASIC authentication;
+
+<tt>agent.connection.sslProtocol</tt>
+: defines what SSL protocol is to be used for creating secure connections to
the ACE server, defaults to <tt>TLS</tt>;
+
+<tt>agent.connection.keyfile</tt> and <tt>agent.connection.keypass</tt>
+: provide the keystore file and password that contain the certificate
information for establishing a secure conncetion between agent and server;
+
+<tt>agent.connection.trustfile</tt> and <tt>agent.connection.trustpass</tt>
+: provide the truststore file and password that contain the trusted (server)
certificate(s) for establishing a secure connection between agent and server.
+
+
+When the agent is started, a new target should appear in the ACE server after
you "Retrieve" the latest 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 *unregistered*. 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 check the
"Registered?" option (and optionally the "Auto approve?" option as well) and
close the dialog by pressing "Ok"[^3]. Once a target is registered, it cannot
be unregistered unless it is deleted (using the trash-icon).
-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 *unregistered*. 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"[^2].
### 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 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 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.
+All configuration files[^4] 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.
+In order to let ACE provision your (templated) configuration files to your
target, you need a **resource processor** that is capable of handling the
configuration files. Without such a resource processor, the configuration files
cannot be deployed to your target. See [this
article](/dev-doc/adding-custom-artifact-types.html) for more information about
writing resource processor for your configuration files, or use an existing
one, such as [Felix Autoconf resource
processor](http://felix.apache.org/documentation/subprojects/apache-felix-autoconf.html).
-For example, consider the following configuration file:
+Suppose a valid resource processor is available that recognizes [Java
Properties
XML](http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html),
consider the following configuration file:
:::xml
- <properties>
- <key>ipAddress</key>
- <value>${context.address}</value>
+ <properties version="1.0">
+ <entry key="ipAddress">${context.address}</entry>
+ <entry key="port">${context.port}</entry>
+ <entry key="logLevel">INFO</entry>
</properties>
-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`.
+The <tt>${context.address}</tt> and <tt>${context.port}</tt> represent
variables that can be replaced. The <tt>context.</tt> (including the dot)
prefix is mandatory, and everything after this prefix is user-definable and
considered as variable name. In this example, two variables are expected:
<tt>address</tt> and <tt>port</tt>. The values for these variables can be added
to entities by using the "Tag Editor", available when you double click on an
artifact, feature, distribution or target in the web UI[^5]. It does not really
matter on what entity the variables are actually defined, but in most cases
they are either defined on a distribution and/or target.
+
+Suppose we want to deploy the aforementioned configuration file to two
targets, "target-1", which is supposed to listen on <tt>192.168.2.1:80</tt> and
"target-2", which is supposed to listen on <tt>192.168.2.2:8080</tt>. To make
the configuration file specific for both targets, we simply need to define two
tags on "target-1", like (see also figure 7):
-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.
+* <tt>address</tt> -> <tt>192.168.2.1</tt>;
+* <tt>port</tt> -> <tt>80</tt>.
-**NOTE**: In case a configuration file consists of a variable that cannot be
resolved, it will simply not be replaced, but left as-is.
+And similar tags on "target-2":
+* <tt>address</tt> -> <tt>192.168.2.2</tt>;
+* <tt>port</tt> -> <tt>8080</tt>.
-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.
+<img src="ace_target_tag_editor.png" width="600px" title="Figure 7: Using the
Tag Editor of a target to supply configuration variables." />
+**Figure 7**: Using the Tag Editor of a target to supply configuration
variables.
+
+Under the covers, ACE uses Velocity[^6] 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. See the Velocity documentation for
more information on how to use this functionality.
+
+**NOTE**: In case a variable cannot be resolved, it will simply not be
replaced, but left as-is. This could lead to invalid or unparsable artifacts on
your target!
+
+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
"target-1" and "target-2" will get a processed version of the configuration
file, each with its own 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 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!
+[^2]: This is a limitation of the current web UI. It is possible to create
more sophisticated associations by using the REST API or the Gogo shell
commands.
+
+[^3]: Do not forget to store your changes!
+
+[^4]: In fact any artifact can be considered as an template, but by default
ACE only considers configuration files.
-[^3]: In fact any artifact can be considered as an template, but by default
ACE only considers configuration files.
+[^5]: In other UIs, such as the Gogo shell, you need to supply these tags
manually.
-[^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/).
+[^6]: 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/).
@@ -153,4 +209,4 @@ ACE will scan all configuration files an
*[DTAP]: Development, Testing, Acceptance and Production
-*[CI]: Continuous Integration
\ No newline at end of file
+*[CI]: Continuous Integration
