. . .

Update

This page describes how an installation of ApiOmat is updated.

Preparations

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

Backup

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

ApiOmat

Linux

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

apt-get update
apt-get upgrade apiomat-yambas apiomat-dashboard2

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 you'll have two options when asked to select which components and dependencies to install:

  • 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".

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

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.

Uninstall

  • 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 Control Panel and click on "Programs and Features", select yambas and the Dashboard and uninstall them with the uninstall wizard.

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)

* link only available in Enterprise Documentation