Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Introduction</h1><p>The Cargo Daemon is a Web-based application that uses the Cargo API to configure, start and stop containers on a remote machine.</p><p>The daemon is meant to be listening 24/7, to allow users to deploy new containers and web applications at their command.</p><p>It can be accessed using a browser-based UI, via Java API or Maven2 plugin.</p><h1>Why use the Cargo Daemon?</h1><p>Most web containers (e.g. Tomcat, Jetty) provide built-in remote deployment facilities already, also many of them already have daemon integrations; so why use the Cargo Daemon?</p><ul><li><strong>During intense redeployment</strong> (i.e., testing and even sometimes QA or production hot deployments): All of the remote deployment facilities that keep the JVM alive will eventually suffer from the dreaded <code>java.lang.OutOfMemoryError: PermGen space</code> exception if something in the web application is leaking memory.<br />Most web containers try their best to track down these 'dead' objects and forcefully remove them, but it does not always succeed to reclaim the memory. With a leaking web application, the available memory starts to shrink after each redeploy, and eventually the memory is exhausted.<br />The only solution to this is to kill the JVM, and restart it. And that is exactly what the Cargo Daemon tries to manage. It will try to shutdown the web application cleanly, but if that fails it will forcefully kill the JVM.<br />It is the only way to guarantee that a new version of your web application always starts when you want it to.</li><li><strong>In heterogeneous environments</strong>: With Cargo, the way you configure the container is independent from the underlying server -you can set the different <a class="confluence-link" href="/display/CARGO/Configuration+properties" data-linked-resource-id="13096" data-linked-resource-type="page" data-linked-resource-default-alias="Configuration properties" data-base-url="http://docs.codehaus.org">configuration properties</a>, define <a class="confluence-link" href="/display/CARGO/DataSource+and+Resource+Support" data-linked-resource-id="116359224" data-linked-resource-type="page" data-linked-resource-default-alias="DataSource and Resource Support" data-base-url="http://docs.codehaus.org">datasources</a>, add <a class="confluence-link" href="/display/CARGO/Deployer" data-linked-resource-id="22203" data-linked-resource-type="page" data-linked-resource-default-alias="Deployer" data-base-url="http://docs.codehaus.org">deployables</a>, etc. transparently. You can therefore use the Cargo Daemon as a container-independent daemon, with support for the generation of the proper configuration on all supported containers.</li><li><strong>During upgrades and/or application server product evaluations</strong>: As Cargo is not dependent on the application server nor on its version, you can easily reuse an existing Cargo Daemon setup to use it for another version of a container, or another container altogether; without having to worry about understanding how to configure it.</li></ul><h1>Table of Contents</h1><p>The documentatation for the Cargo Daemon includes:</p><ul><li><a class="confluence-link" href="#installation" data-anchor="installation" data-linked-resource-default-alias="installation" data-base-url="http://docs.codehaus.org">Installation</a>: explains how to install and run the daemon</li><li><a class="confluence-link" href="#gettingStarted" data-anchor="gettingStarted" data-linked-resource-default-alias="gettingStarted" data-base-url="http://docs.codehaus.org">Getting started</a>: very quick guide on using the daemon</li></ul><h1><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e2FuY2hvcjppbnN0YWxsYXRpb259&amp;locale=en_GB&amp;version=2" data-macro-name="anchor" data-macro-default-parameter="installation"></h1><h1>Installation</h1><table class="wysiwyg-macro" data-macro-name="info" data-macro-parameters="title=Java versions for running the Daemon" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm86dGl0bGU9SmF2YSB2ZXJzaW9ucyBmb3IgcnVubmluZyB0aGUgRGFlbW9ufQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>Cargo Daemon requires Java 6 or greater in order to run in standalone mode.</p><p>If you deploy the Cargo Daemon WAR file on an existing container, the minimum requirement is Java version 5.</p></td></tr></table><p>To install and run the Cargo Daemon:</p><ol><li>Download the Cargo Daemon from the <a class="confluence-link" href="/display/CARGO/Downloads" data-linked-resource-id="10844" data-linked-resource-type="page" data-linked-resource-default-alias="Downloads" data-base-url="http://docs.codehaus.org">Downloads</a> page</li><li>Execute by typing:</li></ol><table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="language=bash" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9YmFzaH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>java -jar target/cargo-daemon-webapp-&lt;version>.war</pre></td></tr></table><p style="margin-left: 30.0px;">where &lt;version&gt; is the version number of the daemon that you have downloaded.</p><p>By default, the Cargo Daemon will run on HTTP port <code>18000</code>. To change it, use the <code>-p</code> option:</p><table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="language=bash" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9YmFzaH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>java -jar target/cargo-daemon-webapp-&lt;version>.war -p 18001</pre></td></tr></table><p>Additionally, Cargo Daemon will save log files in the cargo home directory unless the <code>-nologging</code> option is used.</p><p><span style="font-size: 10.0pt;line-height: 13.0pt;">Note that the Cargo Daemon is a WAR file; you can actually also deploy it as a WAR on any existing container. This can be useful if you want to, for example, reuse a certain security configuration.</span></p><p> </p><p>The daemon also accepts other parameters, in the form of system properties:</p><table class="confluenceTable"><tbody><tr><th class="confluenceTh"><p>Property name</p></th><th class="confluenceTh"><p>Description</p></th><th class="confluenceTh"><p>Mandatory?</p></th><th class="confluenceTh"><p>Default value</p></th></tr><tr><td class="confluenceTd"><p><code>daemon.home</code></p></td><td class="confluenceTd"><p>Directory in which the standaone daemon server stores its files. These include the temporary files (such as its own WAR and server temporary files) as well as the server log files (<code>AWS-xxxxxxxxxxxxx.log</code>, where <code>xxxxxxxxxxxxx</code> is the timestamp at which the deamon was started).</p><p>This property is not used and completely ignored if the daemon WAR file is deployed on an existing container.</p></td><td class="confluenceTd"><p><img class="emoticon emoticon-thumbs-down" data-emoticon-name="thumbs-down" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/thumbs_down.png" alt="(thumbs down)" title="(thumbs down)" /></p></td><td class="confluenceTd"><p><code>${user.home}/.cargo</code></p></td></tr><tr><td class="confluenceTd"><p><code>cargo.home</code></p></td><td class="confluenceTd"><p>Directory in which the daemon (be it standalone or deployed on an existing container) stores the list of containers, downloaded container archives, container logs, etc.</p></td><td class="confluenceTd"><p><img class="emoticon emoticon-thumbs-down" data-emoticon-name="thumbs-down" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/thumbs_down.png" alt="(thumbs down)" title="(thumbs down)" /></p></td><td class="confluenceTd"><p><code>${user.home}/.cargo</code></p><p>Note that the standalone daemon by default sets this to <code>${daemon.home}</code></p></td></tr></tbody></table><h1><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e2FuY2hvcjpnZXR0aW5nU3RhcnRlZH0&amp;locale=en_GB&amp;version=2" data-macro-name="anchor" data-macro-default-parameter="gettingStarted"></h1><h1>Getting started using the browser UI</h1><p>To use the Cargo Daemon via the browser UI, simply open <code>http://&lt;machine&gt;:&lt;port&gt;/</code> -where <code>&lt;machine&gt;</code> is the machine host name or IP address and <code>&lt;port&gt;</code> is the port number used (default is <code>18000</code>):</p><ul><li>To start a container, fill in the form and press <strong>Start</strong>:<br /><br /><img class="confluence-embedded-image" confluence-query-params="effects=drop-shadow" src="/download/attachments/231080058/Container+options.png?version=1&amp;modificationDate=1369297716704&amp;effects=drop-shadow" data-image-src="/download/attachments/231080058/Container+options.png?version=1&amp;modificationDate=1369297716704&amp;effects=drop-shadow" data-linked-resource-id="231375419" data-linked-resource-type="attachment" data-linked-resource-default-alias="Container options.png" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080058" title="null > Container options.png"><br /><br /></li><li>To <strong>stop</strong>, <strong>restart</strong>, <strong>delete</strong> or <strong>view logs</strong> of a container, use the actions on the containers list:<br /><img class="confluence-embedded-image" confluence-query-params="effects=drop-shadow" src="/download/attachments/231080058/Container+actions.png?version=1&amp;modificationDate=1369297716732&amp;effects=drop-shadow" data-image-src="/download/attachments/231080058/Container+actions.png?version=1&amp;modificationDate=1369297716732&amp;effects=drop-shadow" data-linked-resource-id="231375420" data-linked-resource-type="attachment" data-linked-resource-default-alias="Container actions.png" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080058" title="null > Container actions.png"></li><li>The Cargo Daemon keeps a persistent record on disk of all the containers that have been submitted. Containers that have been submitted will stay in the list, even when they are stopped. This allows you to manually restart them, or view the logs even after the container is stopped.</li><li>If you want the container to be removed from the list, simply press the <strong>delete</strong> button.</li><li>Containers can also be submitted with the <code>autostart</code> property, this will automatically restart the container if the daemon notices it is stopped.</li></ul><h1><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e2FuY2hvcjpnZXR0aW5nU3RhcnRlZH0&amp;locale=en_GB&amp;version=2" data-macro-name="anchor" data-macro-default-parameter="gettingStarted"></h1><h1>Getting started with the Java API / Maven2/Maven3 plugin</h1><p>As stated before, the Cargo Daemon is also available programmatically:</p><ul><li>The details of the Java API can be seen on the <a href="http://cargo.codehaus.org/maven-site/cargo-extensions/apidocs/index.html?org/codehaus/cargo/tools/daemon/DaemonClient.html">Javadoc for o.c.c.tools.daemon.DaemonClient</a></li><li class="confluence-link">The details of the configuration for the Maven2/Maven3 plugin is documented in the <span class="confluence-link"> </span><a class="confluence-link" href="/display/CARGO/Maven2+Plugin+Reference+Guide#Maven2PluginReferenceGuide-daemon" data-anchor="daemon" data-linked-resource-id="61971" data-linked-resource-type="page" data-linked-resource-default-alias="Maven2 Plugin Reference Guide#daemon" data-base-url="http://docs.codehaus.org"><span class="confluence-link">Daemon configuration section of the Maven2/Maven3 plugin reference guide</span></a> and the example can be seen via the <a class="confluence-link" href="/display/CARGO/Maven2+Archetypes#Maven2Archetypes-daemon" data-anchor="daemon" data-linked-resource-id="74316" data-linked-resource-type="page" data-linked-resource-default-alias="Maven2 Archetypes#daemon" data-base-url="http://docs.codehaus.org"><span class="confluence-link"><span class="confluence-link"><span class="confluence-link">Daemon archetype</span></span></span></a>.</li></ul><p> </p><table class="wysiwyg-macro" data-macro-name="info" data-macro-parameters="title=Java versions for connecting to the Daemon via Java API or Maven2/Maven3 plugin" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm86dGl0bGU9SmF2YSB2ZXJzaW9ucyBmb3IgY29ubmVjdGluZyB0byB0aGUgRGFlbW9uIHZpYSBKYXZhIEFQSSBvciBNYXZlbjIvTWF2ZW4zIHBsdWdpbn0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>In order to connect to the Daemon via Java API or Maven2/Maven3 plugin, the minimum requirement is Java version 5.</p><p>To get the required libraries for using the Daemon via Java API, please check the <a class="confluence-link" href="/display/CARGO/Downloads" data-linked-resource-id="10844" data-linked-resource-type="page" data-linked-resource-default-alias="Downloads" data-base-url="http://docs.codehaus.org">Downloads</a> page.</p></td></tr></table>