| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Upgrading the Broker</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Upgrading the Broker</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.32.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#general-upgrade-procedure">1. General Upgrade Procedure</a></li> |
| <li><a href="#upgrading-tool">2. Upgrading tool</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache ActiveMQ "Classic" (and previous versions) is runnable out of the box by executing the command: <code>./bin/activemq run</code>. |
| The ActiveMQ Artemis broker follows a different paradigm where the project distribution serves as the broker "home" and one or more broker "instances" are created which reference the "home" for resources (e.g. jar files) which can be safely shared between broker instances. |
| Therefore, an instance of the broker must be created before it can be run. |
| This may seems like an overhead at first glance, but it becomes very practical when updating to a new Artemis version for example.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To create an Artemis broker instance navigate into the Artemis home folder and run: <code>./bin/artemis create /path/to/myBrokerInstance</code> on the command line.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Because of this separation it’s very easy to upgrade Artemis in most cases.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| It’s recommended to choose a folder different from where Apache Artemis was downloaded. |
| This separation allows you run multiple broker instances with the same Artemis "home" for example. |
| It also simplifies updating to newer versions of Artemis. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="general-upgrade-procedure"><a class="anchor" href="#general-upgrade-procedure"></a><a class="link" href="#general-upgrade-procedure">1. General Upgrade Procedure</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Upgrading may require some specific steps noted in the <a href="versions.html#versions">versions</a>, but the general process is as follows:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Navigate to the <code>etc</code> folder of the broker instance that’s being upgraded</p> |
| </li> |
| <li> |
| <p>Open <code>artemis.profile</code> (<code>artemis.profile.cmd</code> on Windows). |
| It contains a property which is relevant for the upgrade:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">ARTEMIS_HOME='/path/to/apache-artemis-version'</pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>If you run Artemis as a service on windows you have to do the following additional steps:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Navigate to the <code>bin</code> folder of the broker instance that’s being upgraded</p> |
| </li> |
| <li> |
| <p>Open <code>artemis-service.xml</code>. |
| It contains a property which is relevant for the upgrade:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap"><env name="ARTEMIS_HOME" value="/path/to/apache-artemis-version"/></pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>ARTEMIS_HOME</code> property is used to link the instance with the home. |
| <em>In most cases</em> the instance can be upgraded to a newer version simply by changing the value of this property to the location of the new broker home. |
| Please refer to the aforementioned <a href="versions.html#versions">versions</a> document for additional upgrade steps (if required).</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is also possible to do many of these update steps automatically as can be seen in the next section.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="upgrading-tool"><a class="anchor" href="#upgrading-tool"></a><a class="link" href="#upgrading-tool">2. Upgrading tool</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>An upgrade helper tool from the new broker download can be used to refresh various configuration files and scripts from an existing broker instance from a prior version, and thus automate much of work to upgrade the instance to use the new version.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| You should back up your existing broker instance before running the command. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="shell"><span class="nb">cd</span> <span class="nv">$NEW_ARTEMIS_DOWNLOAD</span>/bin/ |
| ./artemis upgrade PATH_TO_UPGRADING_INSTANCE</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The broker instance <code>bin/artemis</code> script and <code>etc/artemis.profile</code>(<code>artemis.cmd</code> and <code>artemis.cmd.profile</code> on Windows) will be updated to the new versions, setting its ARTEMIS_HOME to refer to the new broker version home path. |
| The tool will also create the new <code><instance>/etc/log4j2.properties</code> configuration file if needed (e.g if you are migrating from a version prior to 2.27.0), and remove the old <code><instance>/etc/logging.properties</code> file if present.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>broker.xml</code> file and data are retained as-is.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>Most existing customisations to the old configuration files and scripts will be lost in the process of refreshing the files. |
| As such you should compare the old configuration files with the refreshed ones and then port any missing customisations you may have made as necessary. |
| The upgrade command itself will copy the older files it changes to an <code>old-config-bkp.</code> folder within the instance dir.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Similarly, if you had customised the old <code>logging.properties</code> file you may need to prepare analogous changes for the new <code>log4j2.properties</code> file.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
