Github user tbouron commented on a diff in the pull request: https://github.com/apache/brooklyn-docs/pull/212#discussion_r140823147 --- Diff: guide/ops/upgrade.md --- @@ -0,0 +1,356 @@ +--- +title: Upgrade +layout: website-normal +--- + +This guide provides all necessary information to upgrade Apache Brooklyn for both the RPM/DEB and Tarball packages. + +## Backwards Compatibility + +Apache Brooklyn version 0.12.0 onward runs primarily inside a Karaf container. When upgrading from 0.11.0 or below, +this update changes the mechanisms for launching Brooklyn. +This will impact any custom scripting around the launching of Brooklyn, and the supplying of command line arguments. + +Use of the `lib/dropins` and `lib/patch` folders will no longer work (because Karaf does not support that kind of classloading). +Instead, code must be built and installed as [OSGi bundles](https://en.wikipedia.org/wiki/OSGi#Bundles). + +## Upgrading + +* Use of RPM and DEB is now recommended where possible, rather than the tar.gz. This entirely replaces the previous install. + +* CentOS 7.x is recommended over CentOS 6.x (note: the RPM **will not work** on CentOS 6.x) + +### Upgrade from Apache Brooklyn 0.12.0 onward + +{::options parse_block_html="true" /} + +<ul class="nav nav-tabs"> + <li class="active impl-1-tab"><a data-target="#impl-1, .impl-1-tab" data-toggle="tab" href="#">RPM / DEB Packages</a></li> + <li class="impl-2-tab"><a data-target="#impl-2, .impl-2-tab" data-toggle="tab" href="#">Tarball</a></li> +</ul> + +<div class="tab-content"> +<div id="impl-1" class="tab-pane fade in active"> + +1. **Important!** Backup persisted state and custom configuration, in case you need to rollback to a previous version. + + 1. By default, persisted state is located at `/var/lib/brooklyn`. + The `persistenceDir` and `persistenceLocation` are configured in the file `/etc/brooklyn/org.apache.brooklyn.osgilauncher.cfg`. + The persistence details will be logged in `/var/log/brooklyn/brooklyn.info.log` at startup time. + + 2. Configuration files are in `/etc/brooklyn`. + +2. Upgrade Apache Brooklyn: + + 1. [Download](../misc/download.html) the new RPM/DEB package + + 2. Upgrade Apache Brooklyn: + + # CentOS / RHEL + sudo yum upgrade apache-brooklyn-xxxx.noarch.rpm + + # Ubuntu / Debian + sudo dpkg -i apache-brooklyn-xxxx.all.deb + + If there are conflicts in configuration files (located in `/etc/brooklyn`), the upgrade will behave differently based + on the package you are using: + + * RPM: the upgrade will keep the previously installed one and save the new version, with the suffix `.rpmsave`. + You will then need to check and manually resolve those. + * DEB: the upgrade will ask you what to do. + +3. Start Apache Brooklyn: + + # CentOS 7 / RHEL + sudo systemctl start brooklyn + # CentOS 6 and older + sudo initctl start brooklyn + + # Ubuntu / Debian + start brooklyn + + Wait for Brooklyn to be running (i.e. its web-console is responsive) + +</div> + +<div id="impl-2" class="tab-pane fade"> + +1. Stop Apache Brooklyn: + + ./bin/stop brooklyn + + If this does not stop it within a few seconds (as checked with `sudo ps aux | grep karaf`), then use `sudo kill <JAVA_PID>` + +2. **Important!** Backup persisted state and custom configuration. + + 1. By default, persisted state is located at `~/.brooklyn/brooklyn-persisted-state`. + The `persistenceDir` and `persistenceLocation` are configured in the file `./etc/org.apache.brooklyn.osgilauncher.cfg`. + The persistence details will be logged in `./log/brooklyn.info.log` at startup time. + + 2. Configuration files are in `./etc/`. + Any changes to these configuration files will need to be re-applied after reinstalling Brooklyn. + +3. Install new version of Apache Brooklyn: + + 1. [Download](../misc/download.html) the new tarball zip package. + + 2. Install Brooklyn: + + tar -zxf apache-brooklyn-xxxx.tar.gz + cd apache-brooklyn-xxxx + +4. Restore any changes to the configuration files (see step 2). + +5. Validate that the new release works, by starting in "HOT_BACKUP" mode. + + 1. Before starting Brooklyn, reconfigure `./etc/org.apache.brooklyn.osgilauncher.cfg` and set `highAvailabilityMode=HOT_BACKUP`. + This way when Brooklyn is started, it will only read and validate the persisted state and will not write into it. + + 2. Start Apache Brooklyn: + + ./bin/start brooklyn + + 3. Check whether you have rebind ERROR messages in `./log/brooklyn.info.log`, e.g. `sudo grep -E "WARN|ERROR" /opt/brooklyn/log/brooklyn.debug.log`. + If you do not have such errors you can proceed. + + 4. Stop Apache Brooklyn: + + ./bin/stop brooklyn + + 5. Change the `highAvailabilityMode` to the default (AUTO) by commenting it out in `./etc/org.apache.brooklyn.osgilauncher.cfg`. + +6. Start Apache Brooklyn: + + ./bin/start brooklyn + + Wait for Brooklyn to be running (i.e. its web-console is responsive). + +7. Update the catalog, using the br command: + + 1. Download the br tool (i.e. from the "CLI Download" link in the web-console). + + 2. Login with br: `br login http://localhost:8081 <user> <password>`. + + 3. Update the catalog: `br catalog add /opt/brooklyn/catalog/catalog.bom`. + +</div> +</div> + +### Upgrade from Apache Brooklyn 0.11.0 and below + +<ul class="nav nav-tabs"> + <li class="active impl-1-tab"><a data-target="#impl-1, .impl-1-tab" data-toggle="tab" href="#">RPM / DEB Packages</a></li> + <li class="impl-2-tab"><a data-target="#impl-2, .impl-2-tab" data-toggle="tab" href="#">Tarball</a></li> +</ul> + +<div class="tab-content"> +<div id="impl-1" class="tab-pane fade in active"> + +1. Stop Apache Brooklyn: + + # CentOS 7 / RHEL + sudo systemctl stop brooklyn + # CentOS6 and older + sudo initctl stop brooklyn + + # Ubuntu / Debian + stop brooklyn + + If this does not stop it within a few seconds (as checked with `sudo ps aux | grep brooklyn`), then use `sudo kill <JAVA_PID>`. + +2. **Important!** Backup persisted state and custom configuration. + + 1. By default, persisted state is located at `/opt/brooklyn/.brooklyn/`.. + The `persistenceDir` and `persistenceLocation` are configured in the file `./etc/org.apache.brooklyn.osgilauncher.cfg`. + The persistence details will be logged in `./log/brooklyn.info.log` at startup time. + + 2. Configuration files are in `./etc/`. + Any changes to these configuration files will need to be re-applied after reinstalling Brooklyn. + +3. Delete the existing Apache Brooklyn install: + + 1. Remove Brooklyn package: + + # CentOS / RHEL + sudo yum erase apache-brooklyn + + # Ubuntu / Debian + sudo dpkg -r apache-brooklyn + + 2. On CentOS 7 run `sudo systemctl daemon-reload`. + + 3. Confirm that Brooklyn is definitely not running (see step 1 above). + + 4. Delete the Brooklyn install directory: `sudo rm -r /opt/brooklyn`. + +4. Make sure you have Java 8. + By default CentOS images come with JRE6 which is incompatible version for Brooklyn. + If CentOS is prior to 6.8 upgrade nss: `yum -y upgrade nss` + +5. Install new version of Apache Brooklyn: + + 1. [Download](../misc/download.html) the new RPM/DEB package. + + 2. Install Apache Brooklyn: + + # CentOS / RHEL + sudo yum install apache-brooklyn-xxxx.noarch.rpm + + # Ubuntu / Debian + sudo dpkg -i apache-brooklyn-xxxx.all.deb + + 3. Wait for Brooklyn to be fully started (i.e. its web-console to be responsive). --- End diff -- Brooklyn does not start automatically, I'm missing a step here. Thanks @aledsage
---