. . .

Update

This page describes how an installation of ApiOmat is updated.

1. Preparations

Before you begin, ensure that monitoring systems and other administrators are notified about possible outages.

2. Backup ApiOmat

MongoDB

Create a dump of the MongoDB database.

  1. The "apiomat" database, which contains Modules, MetaModels and other data: mongodump --db apiomat --out /path

  2. The databases of all your applications, which contain the actual data of your applications (objects of the User class and other classes you defined). For example:

    • mongodump --db TestApp --out /path1

    • mongodump --db TestApp-staging --out /path2

    • mongodump --db TestApp-test --out /path3

If you want to dump all databases, just leave out the --db argument: mongodump --out /path

Configuration files

Back up configuration files.

  • Linux: /etc/apiomat/

  • Windows: C:\Program Files\ApiOmat\config

3. Update ApiOmat

This section describes how to update ApiOmat Yambas and Dashboard. The update guide of the optional product Analytics is explained under Updating Analytics and should be executed after last step of this page.

Linux

Repository change

The repository location has changed starting with ApiOmat version 2.6. Please update your settings, if necessary.

Updating Dashboard from 2.5 to 3.0

  1. Backup files [OPTIONAL]: If you have done specific changes to following files, you may need to backup them before updating from 2.5 to 3.0, especially when you've set up ssl configurations:

    1. /etc/apiomat/001-yambas.conf

    2. /etc/apiomat/aom-dashboard.conf or apiomat-dashboard2.conf (only that one which is used as symlink as apache2 vhost)

  2. Remove Dashboard and (if installed) Dashboard 3 Beta and old php5 packages

    sudo apt-get remove apiomat-dashboard*
    #only if dashboard2 was installed with php5 (default)
    sudo apt-get remove php*
    sudo yum remove apiomat-dashboard*
    #only if dashboard2 was installed with php5 (default)
    sudo yum remove php*

  3. add php7 repositories and install dashboard 3 package

    #ubuntu 14
    sudo add-apt-repository ppa:ondrej/php -y
     
    #debian 8
    echo 'deb http://packages.dotdeb.org jessie all' > /etc/apt/sources.list.d/dotdeb.list
    curl http://www.dotdeb.org/dotdeb.gpg | apt-key add -
     
     
    #update and install
    sudo apt-get update
    sudo apt-get install apiomat-dashboard
    #CentOS 6.X:
    sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
    sudo rpm -Uvh https://mirror.webtatic.com/yum/el6/latest.rpm
     
    #CentOS 7.X:
    sudo rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-7.rpm
    sudo rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
     
     
    #install
    sudo yum --nogpgcheck install apiomat-dashboard

If you don't want to use php7 (for whatever reasons), you can still use the php5 dashboard installer, so that you don't need to add php7 repositories (in step 3). The package name is apiomat-dashboard-php5.

For example in Ubuntu, execute the following commands on one server:

apt-get update
apt-get upgrade apiomat-yambas apiomat-dashboard
sudo yum update
sudo yum --nogpgcheck update apiomat-yambas
sudo yum --nogpgcheck update apiomat-dashboard

Note that the package name of dashboard has changed! This means, that you can't update from 2.5 to 3.0 - you have to remove (not purge) the old apiomat-dashboard2 package and then install the apiomat-dashboard package. It is helpful to backup the vhost config file /opt/apiomat-dashboard2.conf. See here for an installation guide.

Wait until the previous tomcat log prints "YAMBAS vxy started, took xxxxx ms"". Then repeat for other servers in your cluster.

Windows

Obtain the installers for yambas and the Dashboard, for example "apiomat_yambas_setup_2.5.0.exe" and "apiomat_dashboard_setup_2.5.0.exe".

Execute the yambas installer. In the installer GUI, when asked to select which components and dependencies to install, you have two options:

  • Uncheck all the boxes. In this case, you need to obtain the newest version of the config files (especially apiomat.yaml) manually and check if any new values were introduced that you might need to add to your previously used apiomat.yaml. You can use a tool like WinMerge to see the differences between the files, which makes this easy.

  • Uncheck all boxes except for the yambas configuration. In this case you need to manually change the config file according to your needs. You should have a copy of your previously used one, so you can use a tool like WinMerge to see the differences between the files, which makes this easy.

Execute the Dashboard installer. In the installer GUI, when asked to select which components and dependencies to install, uncheck all the checkboxes.

You might have to manually start the services. Either run "services.msc" or open the task manager, click on the "services" tab and then click on "launch services" at the bottom. Start "Apache" and "Tomcat".

Manually installed ApiOmat (ZIP / WAR files)

To update your manually installed packages (Yambas WAR file and Dashboard ZIP file) first follow the guide of Uninstallation. Afterwards execute the instruction from Manual installation to install your new ApiOmat version. Finally restore your data backup and configuration files.

4. Checks

  • Check tomcat log for errors (Linux: /var/log/tomcat/catalina.out; Windows: C:\tomcat8\logs\stdout...)

  • Check if everything works: open Dashboard, log in, hit "Deploy", fetch some data in the Data Editor

  • Since 2.6.0 you are able to configure your own password policies (see Password Policy). To make sure your passwordpolicy.json is recognized by ApiOmat Yambas check if /etc/apiomat/aom-yambas contains the JVM argument -Dpasswordpolicy.config=%~4\passwordpolicy.json that leads to your configuration path. Otherwise the internal passwordpolicy.json will be used, so your changes won't take effect.

5. Recover from Errors

When an error occurs, either during update, or when starting Tomcat after the update, or when using ApiOmat after the update, you can go back to the previous version.

The best way to do this is by uninstalling the newly installed version and then re-install the previous version and restore the MongoDB dump and configuration files.

If you update ApiOmat from an earlier version (e.g. 2.2.0) a new config-file (apiomat.yaml) will be added to /etc/apiomat/. Anyway, your "old" yambas.conf will still be in use. If you should run into any trouble with the config-file, please check the yambas.config-parameter for tomcat-startup or in a respective environment variable. For the apiomat.yaml the apiomat.config-parameter is used, but subsequently to yambas.conf.

Furthermore check within the vhost file of the dashboard (/etc/apiomat/aom-dashboard.conf or apiomat-dashboard.conf) if the right environment variable is set:

# old way:
SetEnv yambas.config /etc/apiomat/yambas.conf
 
# new way:
SetEnv apiomat.config /etc/apiomat/apiomat.yaml

If you run into errors then rethink to use the old way.

Uninstall

For uninstallation details see the guides in chapter Uninstallation.
To conclude:

  • Linux: Depending on the distribution you use, there are different ways to fully uninstall a package. Follow your distribution's conventions to uninstall the following packages: apiomat-yambas, apiomat-dashboard2

  • Windows: Open the guide Uninstallation on Windows

Re-install

Follow the steps in Installation.

Keep in mind not to install the newest version, but instead the one you had previously installed!

So in Ubuntu for example, instead of apt-get install apiomat-yambas, execute apt-get install apiomat-yambas=2.4.0

Restore data and configuration files

  • Restore the MongoDB dump:

    • mongorestore --db apiomat /path1

    • mongorestore --db TestApp /path2

    • mongorestore --db TestApp-staging /path3

    • ...

  • Restore the configuration files from your backup location to the locations mentioned above (see Backup -> Configuration files)

Start

Start Apache and Tomcat. Check the logs, check if everything works (open Dashboard, log in, hit "Deploy", fetch some data in the Data Editor)