. . .

Automatic installation

For Microsoft Windows Server 2008 and 2012 (and R2), ApiOmat provides two separate Windows installer files which will install ApiOmat and most necessary third party software automatically.

One installer is for the main backend "yambas" and one installer is for the Web interface "Dashboard".

The only third party software the ApiOmat depends on and that is not installed automatically is MongoDB.

Installing MongoDB

Install YAMBAS

First, go to https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/index.html?token=TOKEN (replace TOKEN with the token we sent you via email) and download the installer "apiomat_yambas_setup_VERSION.exe" (replace VERSION with the version you want to install, for example "2.6.0".

You can also download the installer directly with an HTTP client like cURL with the following URL: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/apiomat_yambas_setup_VERSION.exe?token=TOKEN (again, replace VERSION and TOKEN with the appropriate values).

Upgrade

If upgrading from a previous ApiOmat version, backup all changes and files which were modified manually in the Apache Tomcat subfolders (e.g. shared/lib contents), because all data will be overwritten in the automatic setup.

YAMBAS is the main backend and a crucial component of ApiOmat. To install it, run the setup file "apiomat_yambas_setup_<version>.exe". It will ask for elevated privileges (administrator rights) when being launched.

  1. At the beginning of the setup you can choose an install path. The default one ("C:\Program Files\ApiOmat ") is fine.

  2. Next you have the choice to (de-)select some setup options, but it's best to not change these settings and instead keep the defaults. That's how the installer gets tested.

    1. "Dependency installation": You can (de-)select third party software like Java in case it's already installed.

    2. "Dependency configuration": Configures Apache, Tomcat etc.

    3. "System configuration": Configures NTP, Firewall etc.

    4. "ApiOmat configuration": Copies ApiOmat config files

    In any case, the Tomcat web application files (.war) get installed to the Tomcat webapp directory.
    Please also note that Apache HTTP Server is deactivated by default, because it gets installed by the Dashboard installer. You should only choose to install Apache HTTP Server with the yambas installer if you want to run yambas and Dashboard on different servers.

  3. After extracting third party software installers and ApiOmat files, the setup will launch multiple scripts one after another to install the third party software and ask for setup details. The scripts will run in their own command line windows. Please pay attention to the notifications and questions in the install scripts and provide them with the information they ask for.

    1. Some scripts take several minutes to finish. Please be patient.

    2. Some scripts will show text files that guide you through the installation of a third party software with a GUI. For example the Tomcat installation works with the Tomcat installer GUI. The guide contains info on what options to select in the GUI. Please pay attention to every point, for example currently you shouldn't install Tomcat to its default directory, but to "C:\tomcat8" instead. Also please note that the Tomcat installer GUI should launch in the background, so when the guide is shown, you have to click on the Tomcat installer in the Windows taskbar.

    3. Some scripts contain warnings that you can ignore. For example during the Apache installation there will be a warning regarding the hostname. In the future we will remove these warnings or supply a list with warnings that can be ignored.

  4. When all scripts are finished, you can choose to start the services for Tomcat and Apache.
    Note: Even with selected options, this sometimes doesn't work.

  5. You can also choose to open some URLs like the Apidocs.
    Note: These URLs open on port 8080, because the Apache HTTP Server and the proxy settings don't get installed by default.

  6. After the installation is done, you currently might have to manually start some services. Either run "services.msc" or open the task manager, click on the "services" tab and then click on "launch services" at the bottom.

    1. Choose "MongoDB" and click on "start"/"restart" (this requires that when you installed MongoDB, you also installed the service)

    2. Choose "Apache" and click on "start"/"restart" (not listed in the services because by default the Apache HTTP Server doesn't get installed)

    3. Choose "Tomcat" and click on "start"/"restart"

    4. Wait ~2 minutes for Tomcat to launch ApiOmat

    5. Then refresh the tabs in the browser.

Install Dashboard

First, go to https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/index.html?token=TOKEN (replace TOKEN with the token we sent you via email) and download the installer "apiomat_dashboard_setup_VERSION.exe" (replace VERSION with the version you want to install, for example "3.0.0".

You can also download the installer directly with an HTTP client like cURL with the following URL: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/apiomat_dashboard_setup_VERSION.exe?token=TOKEN (again, replace VERSION and TOKEN with the appropriate values).

The Dashboard is the web interface for managing ApiOmat / yambas. To install it, run the setup file "apiomat_dashboard_setup_<version>.exe". It will ask for elevated privileges (administrator rights) when being launched.

  1. At the beginning of the setup you can choose an install path. The default one ("C:\Program Files\ApiOmat ") is fine.

  2. Next you have the choice to (de-)select some setup options, but it's best to not change these settings and instead keep the defaults. That's how the installer gets tested.

    1. "Dependency installation": You can (de-)select third party software like Apache in case it's already installed, but be aware of possible errors when installation paths of your existing software don't match the ones that are expected by the installer for configuration etc.

    2. "Dependency configuration": Configures Apache, PHP etc.

    3. "System configuration": Configures NTP, Firewall etc.

    4. "ApiOmat configuration": Copies ApiOmat config files

    In any case, the Dashboard gets installed to the Apache HTTP Server htdocs directory.
    Please also note that Apache HTTP Server is activated by default, because it doesn't get installed by the yambas installer. You should only choose not to install Apache HTTP Server with the Dashboard installer if you already installed it with the yambas installer. In that case some adjustments need to be made in the httpd.conf file. Please contact the support for further assistance.
    Note:
    Since 2.5.1 the configuration setting "Include conf/extra/httpd-mpm.conf" is enabled in httpd.conf.This will set the configuration for Multi-Processing Modules (Threading configurations etc.). As it is described on apache.org: "Apache httpd can more cleanly and efficiently support a wide variety of operating systems. In particular, the Windows version of the server is now much more efficient."

  3. After extracting third party software installers and ApiOmat files, the setup will launch multiple scripts one after another to install the third party software and ask for setup details. The scripts will run in their own command line windows. Please pay attention to the notifications and questions in the install scripts and provide them with the information they ask for.

    1. Some scripts take several minutes to finish. Please be patient.

    2. Some scripts will show text files that guide you through the installation of a third party software. For example the PEAR installation is interactive and the shown guide contains info on which options to choose.

    3. Some scripts contain warnings that you can ignore. For example during the Apache installation there will be a warning regarding the hostname. In the future we will remove these warnings or supply a list with warnings that can be ignored.

  4. When all scripts are finished, you can choose to start the service for Apache.
    Note: Even with selected options, this sometimes doesn't work.

  5. You can also choose to open the Dashboard URL.

  6. After the installation is done, you currently might have to manually start some services. Either run "services.msc" or open the task manager, click on the "services" tab and then click on "launch services" at the bottom.

    1. Choose "MongoDB" and click on "start"/"restart" (this requires that when you installed MongoDB, you also installed the service)

    2. Choose "Apache" and click on "start"/"restart"

    3. Then refresh the tabs in the browser.

Optional: Install Dashboard3

Optional: if older Dashboard Versions are installed

If you have another dashboard already installed and want to install Dashboard3 next to it, then you have to turn off all additional tasks at "Select Additional Tasks" step.

Adjust older Dashboard Installations

If you install dashboard 3 besides dashboard 2, you can configure the alias of the dashboard2 and dashboard3 in vhost file (C:\Apache24\conf\httpd.conf):

Alias /dashboard3 "C:/Apache24/htdocs/dashboard3/apiomat/"
Alias / "C:/Apache24/htdocs/dashboard/apiomat/"
<Directory "C:/Apache24/htdocs/dashboard/apiomat">
AllowOverride All
...

After editing the .conf-file the apache service needs to be restarted.

Configuration

The location of config files are:

  • C:\Program Files\ApiOmat \config\apiomat.yaml

  • C:\Program Files\ApiOmat\config\log4j.xml

  • C:\Program Files\ApiOmat\config\hazelcast.xml

  • C:\Program Files\ApiOmat\config\security.policy

Next steps

Checks

Logs

  • MongoDB: As provided with the logpath key in the mongodb config

  • The locations of the other logfiles are linked in one single place: C:\Program Files\ApiOmat\logs. The links go to:

    • C:\tomcat8\logs ("CONSOLE" appender / standard output logs here)

    • C:\Users\YourUser\AppData\Local\ApiOmat\logs ("FILE" appender logs here)

    • C:\Apache24\logs

    • C:\Apache24\htdocs\dashboard\apiomat\log

  • To read the logs in a continuous way (show new lines automatically), use the PowerShell cmdlet Get-Content with the "-wait" parameter

    • For example: gc .\catalina.out -tail 100 -wait

HTTP Test

  • yambas: "http://<HOSTNAME>/yambas/rest" - should print the version number

  • Dashboard: "http://<HOSTNAME>"

  • Apidocs: "http://<HOSTNAME>/apidocs"

  • Docs: "http://<HOSTNAME>/docs"

Possible issues

  • The setup already configures the Firewall for opening ports like 80, but in case you set up your machine on an IaaS provider like Microsoft Azure, you also have to open the machine's ports in its management portal.

* link only available in Enterprise Documentation