[jira] [Created] (ACE-474) Clarify our getting started example (running targets)
Marcel Offermans created ACE-474: Summary: Clarify our getting started example (running targets) Key: ACE-474 URL: https://issues.apache.org/jira/browse/ACE-474 Project: ACE Issue Type: Improvement Components: Site Reporter: Marcel Offermans Fix For: next As discussed in this StackOverflow question, we could improve our documentation with some examples of how to run targets: http://stackoverflow.com/questions/23344642/adding-targets-in-apache-ace/ -- This message was sent by Atlassian JIRA (v6.2#6252)
svn commit: r907281 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Author: buildbot Date: Tue Apr 29 10:06:29 2014 New Revision: 907281 Log: Staging update by buildbot for ace Modified: websites/staging/ace/trunk/content/ (props changed) websites/staging/ace/trunk/content/user-doc/user-guide.html Propchange: websites/staging/ace/trunk/content/ -- --- cms:source-revision (original) +++ cms:source-revision Tue Apr 29 10:06:29 2014 @@ -1 +1 @@ -1590009 +1590935 Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html == --- websites/staging/ace/trunk/content/user-doc/user-guide.html (original) +++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29 10:06:29 2014 @@ -246,30 +246,44 @@ To delete an association once is created 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 created2. 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 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. +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, run-target 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 org.apache.ace.agent project. This agent simply does the following: 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; 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. -Dname=value): +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: +$ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar + +Welcome to Apache Felix Gogo +... + + + +The agent can be configured by supplying its options as commandline parameters (e.g. -Dname=value). A list of most used options are7: agent.identification.agentid 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; agent.discovery.serverurls 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 http://localhost:8080 is used; +agent.discovery.checking +defines whether or not server URLs should be checked whether they are alive prior to being used. This implies that a "ping" request is sent to the server URL that is going to be used. Server URLs that are not responding will not be used and will cause another URL (defined by agent.discovery.serverurls) to be picked instead. The default value is true, which means that all server URLs are checked. Use false if your ACE server(s) are not always available or when running the target on a flacky network; agent.logging.level defines the log level of the agent, and should be one of the following values: DEBUG, INFO, WARNING or ERROR. The default log level is INFO; agent.controller.syncinterval -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; +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; agent.controller.syncdelay -defines how long the agent should wait (in seconds) after startup before
svn commit: r1590935 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Author: jawi Date: Tue Apr 29 10:06:24 2014 New Revision: 1590935 URL: http://svn.apache.org/r1590935 Log: ACE-474 - added example on how to run a target. 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=1590935&r1=1590934&r2=1590935&view=diff == --- ace/site/trunk/content/user-doc/user-guide.mdtext (original) +++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:06:24 2014 @@ -100,14 +100,22 @@ Creating dynamic associations is current ## 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 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. +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, run-target 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 org.apache.ace.agent 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. -Dname=value): +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: + +:::sh +$ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar + +Welcome to Apache Felix Gogo +... + +The agent can be configured by supplying its options as commandline parameters (e.g. -Dname=value). A list of most used options are[^7]: agent.identification.agentid : 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; @@ -115,23 +123,32 @@ The agent can be configured by supplying agent.discovery.serverurls : 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 http://localhost:8080 is used; +agent.discovery.checking +: defines whether or not server URLs should be checked whether they are alive prior to being used. This implies that a "ping" request is sent to the server URL that is going to be used. Server URLs that are not responding will not be used and will cause another URL (defined by agent.discovery.serverurls) to be picked instead. The default value is true, which means that all server URLs are checked. Use false if your ACE server(s) are not always available or when running the target on a flacky network; + agent.logging.level : defines the log level of the agent, and should be one of the following values: DEBUG, INFO, WARNING or ERROR. The default log level is INFO; agent.controller.syncinterval -: 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; +: 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; agent.controller.syncdelay -: 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; +: 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
svn commit: r907283 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Author: buildbot Date: Tue Apr 29 10:13:08 2014 New Revision: 907283 Log: Staging update by buildbot for ace Modified: websites/staging/ace/trunk/content/ (props changed) websites/staging/ace/trunk/content/user-doc/user-guide.html Propchange: websites/staging/ace/trunk/content/ -- --- cms:source-revision (original) +++ cms:source-revision Tue Apr 29 10:13:08 2014 @@ -1 +1 @@ -1590935 +1590937 Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html == --- websites/staging/ace/trunk/content/user-doc/user-guide.html (original) +++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29 10:13:08 2014 @@ -252,7 +252,7 @@ To delete an association once is created 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; it check whether or not software updates are available. If so, it will download it and install this update automatically. -Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: $ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar Welcome to Apache Felix Gogo @@ -347,7 +347,7 @@ In order to let ACE provision your (temp 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 http://velocity.apache.org/";>Velocity website. ↩ -All recognized options can be found in org.apache.ace.agent.AgentConstants. ↩ +A complete list of recognised options can be found in https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java";>org.apache.ace.agent.AgentConstants. ↩
svn commit: r1590937 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Author: jawi Date: Tue Apr 29 10:13:04 2014 New Revision: 1590937 URL: http://svn.apache.org/r1590937 Log: minor markup corrections. 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=1590937&r1=1590936&r2=1590937&view=diff == --- ace/site/trunk/content/user-doc/user-guide.mdtext (original) +++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:13:04 2014 @@ -107,7 +107,7 @@ ACE provides a runnable eclipse project, 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. -Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: :::sh $ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar @@ -220,7 +220,7 @@ ACE will scan all configuration files an [^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/). -[^7]: All recognized options can be found in `org.apache.ace.agent.AgentConstants`. +[^7]: A complete list of recognised options can be found in [`org.apache.ace.agent.AgentConstants`](https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java). *[OBR]: OSGi Bundle Repository
svn commit: r1590938 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Author: jawi Date: Tue Apr 29 10:17:15 2014 New Revision: 1590938 URL: http://svn.apache.org/r1590938 Log: yet some more markup corrections. 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=1590938&r1=1590937&r2=1590938&view=diff == --- ace/site/trunk/content/user-doc/user-guide.mdtext (original) +++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:17:15 2014 @@ -107,10 +107,13 @@ ACE provides a runnable eclipse project, 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. -Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example (the backslash denote line continuations): :::sh -$ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar +$ java \ +-Dagent.identification.agentid=target-1 \ +-Dagent.discovery.serverurls=http://my.ace.server:8080 \ +-jar target.jar Welcome to Apache Felix Gogo ...
svn commit: r907284 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Author: buildbot Date: Tue Apr 29 10:17:20 2014 New Revision: 907284 Log: Staging update by buildbot for ace Modified: websites/staging/ace/trunk/content/ (props changed) websites/staging/ace/trunk/content/user-doc/user-guide.html Propchange: websites/staging/ace/trunk/content/ -- --- cms:source-revision (original) +++ cms:source-revision Tue Apr 29 10:17:20 2014 @@ -1 +1 @@ -1590937 +1590938 Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html == --- websites/staging/ace/trunk/content/user-doc/user-guide.html (original) +++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29 10:17:20 2014 @@ -252,8 +252,11 @@ To delete an association once is created 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; it check whether or not software updates are available. If so, it will download it and install this update automatically. -Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example: -$ java -Dagent.identification.agentid=target-1 -Dagent.discovery.serverurls=http://my.ace.server:8080 -jar target.jar +Since ACE 2.0.1, the binary distribution also contains a single-jar version of a target, called target.jar, that can be used to bootstrap the ACE management agent on a target host as shown in the following example (the backslash denote line continuations): +$ java \ +-Dagent.identification.agentid=target-1 \ +-Dagent.discovery.serverurls=http://my.ace.server:8080 \ +-jar target.jar Welcome to Apache Felix Gogo ...
svn commit: r1590940 - /ace/site/trunk/content/user-doc/getting-started.mdtext
Author: jawi Date: Tue Apr 29 10:26:51 2014 New Revision: 1590940 URL: http://svn.apache.org/r1590940 Log: Added x-ref to user guide for additional configuration. Modified: ace/site/trunk/content/user-doc/getting-started.mdtext Modified: ace/site/trunk/content/user-doc/getting-started.mdtext URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/getting-started.mdtext?rev=1590940&r1=1590939&r2=1590940&view=diff == --- ace/site/trunk/content/user-doc/getting-started.mdtext (original) +++ ace/site/trunk/content/user-doc/getting-started.mdtext Tue Apr 29 10:26:51 2014 @@ -1,6 +1,6 @@ Title: Getting Started -This guide shows the core functionality of ACE, organizing bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface. +This guide shows the core functionality of ACE, organising bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface. ## Download the distribution @@ -11,15 +11,19 @@ To start using ACE, you must first launc ## Start the ACE server -1. Open a terminal and navigate nto the root of the distribution. -1. Navigate to the sub directory `server-allinone`. -1. Start the server using `java -jar server-allinone.jar` +1. Open a terminal and navigate to the root of the distribution; +1. Navigate to the sub directory `server-allinone`; +1. Start the server using `java -jar server-allinone.jar`. + +The server is configured by means of configuration files found in the conf directory. ## Start an ACE target -1. Open a terminal and navigate into the root of the distribution. -1. Navigate to the sub directory `target`. -1. Start the target using `java -jar target.jar` +1. Open a terminal and navigate into the root of the distribution; +1. Navigate to the sub directory `target`; +1. Start the target using `java -jar target.jar`. + +Configuring the target can by done by supplying it commandline parameters, as described in the [user guide](user-guide.html#running-a-target). ## Provisioning some bundles @@ -27,21 +31,21 @@ Apache ACE has both a Web UI and a [REST The following steps can be followed to get started: -1. Launch a browser and point it to: http://localhost:8080/ace/ You should now be greeted with a login prompt. Log in with user "d" password "f" and you should see a view with 4 empty columns and some buttons at the top of the screen. -1. Click on 'Retrieve' to get the initial version of the repository. The column on the right will show you have a target running with name `defaultTargetID`. The other columns remain empty as this is an initial empty version of the repository. -1. Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...' button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the middle of the window. You can perform this step multiple times if you want to upload more than one bundle. Finally, hit the 'Add' button to add all uploaded artifacts to ACE. -1. Create a feature by clicking on the 'Add Feature...' button. Features are the first level of logical grouping for artifacts. -1. Create a distribution by clicking on the 'Add Distribution...' button. Distributions are another level of logical grouping: you group features into distributions. -1. Drag an artifact onto a feature to create an association between the two. By repeating this process you can associate all relevant artifacts to features. -1. Drag a feature onto a distribution and again repeat this process until you've associated all your features with their relevant distributions. -1. Drag the distribution onto the target to associate it. +1. Launch a browser and point it to: http://localhost:8080/ace/ You should now be greeted with a login prompt. Log in with user "d" password "f" and you should see a view with 4 empty columns and some buttons at the top of the screen; +1. Click on 'Retrieve' to get the initial version of the repository. The column on the right will show you have a target running with name `defaultTargetID`. The other columns remain empty as this is an initial empty version of the repository; +1. Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...' button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the middle of the window. You can perform this step multiple times if you want to upload more than one bundle. Finally, hit the 'Add' button to add all uploaded artifacts to ACE; +1. Create a feature by clicking on the 'Add Feature...' button. Features are the first level of logical grouping for artifacts; +1. Create a distribution by clicking on the 'Add Distribution...' button. Distributions are another level of logical gro
svn commit: r907286 - in /websites/staging/ace/trunk/content: ./ user-doc/getting-started.html
Author: buildbot Date: Tue Apr 29 10:26:56 2014 New Revision: 907286 Log: Staging update by buildbot for ace Modified: websites/staging/ace/trunk/content/ (props changed) websites/staging/ace/trunk/content/user-doc/getting-started.html Propchange: websites/staging/ace/trunk/content/ -- --- cms:source-revision (original) +++ cms:source-revision Tue Apr 29 10:26:56 2014 @@ -1 +1 @@ -1590938 +1590940 Modified: websites/staging/ace/trunk/content/user-doc/getting-started.html == --- websites/staging/ace/trunk/content/user-doc/getting-started.html (original) +++ websites/staging/ace/trunk/content/user-doc/getting-started.html Tue Apr 29 10:26:56 2014 @@ -165,7 +165,7 @@ Home » User-doc Getting Started - This guide shows the core functionality of ACE, organizing bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface. + This guide shows the core functionality of ACE, organising bundles and other artifacts into logical features and distributions and associating those with specific targets, all done using a convenient web interface. Download the distribution To start using ACE, you must first launch a server. If you're a developer, you can do that inside Eclipse, as explained here. Otherwise, you need to download a distribution of the server, unpack it, and start it up: @@ -174,37 +174,39 @@ Start the ACE server -Open a terminal and navigate nto the root of the distribution. -Navigate to the sub directory server-allinone. -Start the server using java -jar server-allinone.jar +Open a terminal and navigate to the root of the distribution; +Navigate to the sub directory server-allinone; +Start the server using java -jar server-allinone.jar. +The server is configured by means of configuration files found in the conf directory. Start an ACE target -Open a terminal and navigate into the root of the distribution. -Navigate to the sub directory target. -Start the target using java -jar target.jar +Open a terminal and navigate into the root of the distribution; +Navigate to the sub directory target; +Start the target using java -jar target.jar. +Configuring the target can by done by supplying it commandline parameters, as described in the user guide. Provisioning some bundles Apache ACE has both a Web UI and a REST API to interact with it. Both use a similar workflow. You start by checking out a copy of the workspace, then you work on that copy, and finally you commit your changes back to the server. The following steps can be followed to get started: -Launch a browser and point it to: http://localhost:8080/ace/ You should now be greeted with a login prompt. Log in with user "d" password "f" and you should see a view with 4 empty columns and some buttons at the top of the screen. -Click on 'Retrieve' to get the initial version of the repository. The column on the right will show you have a target running with name defaultTargetID. The other columns remain empty as this is an initial empty version of the repository. -Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...' button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the middle of the window. You can perform this step multiple times if you want to upload more than one bundle. Finally, hit the 'Add' button to add all uploaded artifacts to ACE. -Create a feature by clicking on the 'Add Feature...' button. Features are the first level of logical grouping for artifacts. -Create a distribution by clicking on the 'Add Distribution...' button. Distributions are another level of logical grouping: you group features into distributions. -Drag an artifact onto a feature to create an association between the two. By repeating this process you can associate all relevant artifacts to features. -Drag a feature onto a distribution and again repeat this process until you've associated all your features with their relevant distributions. -Drag the distribution onto the target to associate it. +Launch a browser and point it to: http://localhost:8080/ace/ You should now be greeted with a login prompt. Log in with user "d" password "f" and you should see a view with 4 empty columns and some buttons at the top of the screen; +Click on 'Retrieve' to get the initial version of the repository. The column on the right will show you have a target running with name defaultTargetID. The other columns remain empty as this is an initial empty version of the repository; +Upload some sample bundles into the artifacts column by first clicking the 'Add Artifact...' button. In the dialog that appears, you can upload a bundle using the 'Upload' button in the middle of the window. Y
svn commit: r1590946 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Author: jawi
Date: Tue Apr 29 10:52:47 2014
New Revision: 1590946
URL: http://svn.apache.org/r1590946
Log:
Added section on how to configure the server.
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=1590946&r1=1590945&r2=1590946&view=diff
==
--- ace/site/trunk/content/user-doc/user-guide.mdtext (original)
+++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:52:47 2014
@@ -98,6 +98,14 @@ There is a subtle, but very important, d
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].
+### Configuring the server
+
+The ACE server is completely modular and therefore can be configured in many
different ways. As such, the configuration of the server is done by using the
Configuration Admin service which is provisioned by means of configuration
files that reside in the conf directory. The filename of each
configuration file equals the service PID of the managed service and **must**
end with .cfg. Directories are considered as managed service factories
of which the directory name equals the service PID.
+
+Configuration files itself are simple Java property files containing key-value
pairs separated by newlines. Configuration values are allowed to contain
"placeholders" or "variables". Everything between ${ and } is
considered a variable and replaced by the value represented by that variable.
For example, consider a variable var that is defined as
"value", then ${var} will be replaced with "value".
Variables can refer to another value in the *same* configuration file, or to a
property that is defined in the OSGi-framework or globally in your system as
environment setting.
+
+The configuration files are watched continuously, allowing you to adjust the
configuration of the ACE server without having to restart it.
+
## 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 *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.
@@ -107,7 +115,7 @@ ACE provides a runnable eclipse project,
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.
-Since ACE 2.0.1, the binary distribution also contains a single-jar version of
a target, called target.jar, that can be used to bootstrap the ACE
management agent on a target host as shown in the following example (the
backslash denote line continuations):
+Since version 1.0, the binary distribution of ACE also contains a single-jar
version of a target, called target.jar, that includes all necessary
software and bundles to start the ACE management agent. It can be used to
quickly bootstrap an ACE management agent on a target host as shown in the
following example (the backslash denote line continuations):
:::sh
$ java \
@@ -118,6 +126,8 @@ Since ACE 2.0.1, the binary distribution
Welcome to Apache Felix Gogo
...
+### Target configuration
+
The agent can be configured by supplying its options as commandline parameters
(e.g. -Dname=value). A list of most used options are[^7]:
agent.identification.agentid
svn commit: r907288 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Author: buildbot
Date: Tue Apr 29 10:52:52 2014
New Revision: 907288
Log:
Staging update by buildbot for ace
Modified:
websites/staging/ace/trunk/content/ (props changed)
websites/staging/ace/trunk/content/user-doc/user-guide.html
Propchange: websites/staging/ace/trunk/content/
--
--- cms:source-revision (original)
+++ cms:source-revision Tue Apr 29 10:52:52 2014
@@ -1 +1 @@
-1590940
+1590946
Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html
==
--- websites/staging/ace/trunk/content/user-doc/user-guide.html (original)
+++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29
10:52:52 2014
@@ -174,9 +174,11 @@
Uploading artifacts
Creating a new
feature, distribution and/or target
Creating associations
+Configuring the server
Running a target
+Target configuration
Using the template engine
for targets
@@ -245,6 +247,10 @@ To delete an association once is created
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 created2.
+Configuring the server
+The ACE server is completely modular and therefore can be configured in
many different ways. As such, the configuration of the server is done by using
the Configuration Admin service which is provisioned by means of configuration
files that reside in the conf directory. The filename of each
configuration file equals the service PID of the managed service and
must end with .cfg. Directories are considered as
managed service factories of which the directory name equals the service
PID.
+Configuration files itself are simple Java property files containing
key-value pairs separated by newlines. Configuration values are allowed to
contain "placeholders" or "variables". Everything between ${ and
} is considered a variable and replaced by the value represented by
that variable. For example, consider a variable var that is defined as
"value", then ${var} will be replaced with "value".
Variables can refer to another value in the same configuration file,
or to a property that is defined in the OSGi-framework or globally in your
system as environment setting.
+The configuration files are watched continuously, allowing you to adjust
the configuration of the ACE server without having to restart it.
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
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, run-target 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 org.apache.ace.agent project. This agent simply does the
following:
@@ -252,7 +258,7 @@ To delete an association once is created
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;
it check whether or not software updates are available. If so, it will
download it and install this update automatically.
-Since ACE 2.0.1, the binary distribution also contains a single-jar version
of a target, called target.jar, that can be used to bootstrap the ACE
management agent on a target host as shown in the following example (the
backslash denote line continuations):
+Since version 1.0, the binary distribution of ACE also contains a
single-jar version of a target, called target.jar, that includes all
necessary software and bundles to start the ACE management agent. It can be
used to quickly bootstrap an ACE management agent on a target host as shown in
the following example (the backslash denote line continuations):
$ java \
-Dagent.identification.agentid=target-1 \
-Dagent.discovery.serverurls=http://my.ace.server:8080 \
@@ -263,6 +269,7 @@ Welcome to Apache Felix Gogo
+Target configuration
The agent can be configured by supplying its options as commandline
parameters (e.g. -Dname=value). A list of most used options are7:
agent.identification.agentid
svn commit: r907289 - in /websites/staging/ace/trunk/content: ./ user-doc/user-guide.html
Author: buildbot Date: Tue Apr 29 10:53:59 2014 New Revision: 907289 Log: Staging update by buildbot for ace Modified: websites/staging/ace/trunk/content/ (props changed) websites/staging/ace/trunk/content/user-doc/user-guide.html Propchange: websites/staging/ace/trunk/content/ -- --- cms:source-revision (original) +++ cms:source-revision Tue Apr 29 10:53:59 2014 @@ -1 +1 @@ -1590946 +1590947 Modified: websites/staging/ace/trunk/content/user-doc/user-guide.html == --- websites/staging/ace/trunk/content/user-doc/user-guide.html (original) +++ websites/staging/ace/trunk/content/user-doc/user-guide.html Tue Apr 29 10:53:59 2014 @@ -273,7 +273,7 @@ Welcome to Apache Felix Gogo The agent can be configured by supplying its options as commandline parameters (e.g. -Dname=value). A list of most used options are7: agent.identification.agentid -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; +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; agent.discovery.serverurls 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 http://localhost:8080 is used; agent.discovery.checking @@ -357,7 +357,7 @@ In order to let ACE provision your (temp 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 http://velocity.apache.org/";>Velocity website. ↩ -A complete list of recognised options can be found in https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java";>org.apache.ace.agent.AgentConstants. ↩ +A complete list of recognised options can be found in https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java";>org.apache.ace.agent.AgentConstants. ↩
svn commit: r907290 - /websites/production/ace/content/
Author: jawi Date: Tue Apr 29 10:53:59 2014 New Revision: 907290 Log: Publishing svnmucc operation to ace site by jawi Added: websites/production/ace/content/ - copied from r907288, websites/staging/ace/trunk/content/
svn commit: r1590947 - /ace/site/trunk/content/user-doc/user-guide.mdtext
Author: jawi Date: Tue Apr 29 10:53:54 2014 New Revision: 1590947 URL: http://svn.apache.org/r1590947 Log: Replaced backticks by tt tags. 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=1590947&r1=1590946&r2=1590947&view=diff == --- ace/site/trunk/content/user-doc/user-guide.mdtext (original) +++ ace/site/trunk/content/user-doc/user-guide.mdtext Tue Apr 29 10:53:54 2014 @@ -131,7 +131,7 @@ Since version 1.0, the binary distributi The agent can be configured by supplying its options as commandline parameters (e.g. -Dname=value). A list of most used options are[^7]: agent.identification.agentid -: 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; +: 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; agent.discovery.serverurls : 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 http://localhost:8080 is used; @@ -233,7 +233,7 @@ ACE will scan all configuration files an [^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/). -[^7]: A complete list of recognised options can be found in [`org.apache.ace.agent.AgentConstants`](https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java). +[^7]: A complete list of recognised options can be found in [org.apache.ace.agent.AgentConstants](https://svn.apache.org/repos/asf/ace/trunk/org.apache.ace.agent/src/org/apache/ace/agent/AgentConstants.java). *[OBR]: OSGi Bundle Repository
svn commit: r907291 - /websites/production/ace/content/
Author: jawi Date: Tue Apr 29 10:56:16 2014 New Revision: 907291 Log: Publishing svnmucc operation to ace site by jawi Added: websites/production/ace/content/ - copied from r907290, websites/staging/ace/trunk/content/
[jira] [Resolved] (ACE-474) Clarify our getting started example (running targets)
[ https://issues.apache.org/jira/browse/ACE-474?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] J.W. Janssen resolved ACE-474. -- Resolution: Fixed Added an example on how to run the target and cross-referenced it from the getting started page. See: http://ace.apache.org/user-doc/user-guide.html#running-a-target > Clarify our getting started example (running targets) > - > > Key: ACE-474 > URL: https://issues.apache.org/jira/browse/ACE-474 > Project: ACE > Issue Type: Improvement > Components: Site >Reporter: Marcel Offermans > Fix For: next > > > As discussed in this StackOverflow question, we could improve our > documentation with some examples of how to run targets: > http://stackoverflow.com/questions/23344642/adding-targets-in-apache-ace/ -- This message was sent by Atlassian JIRA (v6.2#6252)
