. . .

Dashboard Installation

Introduction

Dashboard is the UI to control the setup, accounts, applications and modules of ApiOmat. It controls YAMBAS via its REST interface. That is, all actions done via Dashboard could also be scripted. The Dashboard consists of two parts:

  1. Developer Dashboard

  2. Vendor Onboarding / Sysadmin area

While all so-called Customer accounts are automatically logged into the Developer Dashboard, all organizations and sysadmin are automatically logged into the Vendor Onboarding area.

Prerequisites

Installation of YAMBAS is required!

Open the following port in the firewall:

Port

Transport

Service

Host

Client

80/443

TCP


Webserver

Application Server

Outside World

Install PHP

The security support of PHP 5.6 expired on 31.12.2018, so the dashboard php 5 installation package is deprecated since version 3.2. PHP 7.1 should be installed instead!

Ubuntu 14, 16 and 18

# Add repository for php7. If you want to use php5, you have to use the apiomat-dashboard.php5 package later on!
sudo add-apt-repository ppa:ondrej/php -y
sudo apt-get update

Debian 8

# Add repository for php7. If you want to use php5, you have to use the apiomat-dashboard.php5 package later on!
sudo apt install apt-transport-https lsb-release ca-certificates
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

Debian 9

# Add repository for php7. If you want to use php5, you have to use the apiomat-dashboard.php5 package later on!
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

CentOS 6.X

# If php5 is already installed and you want to use php7,just remove old version of php to avoid conflicts. If you want to use php5 you have to use the apiomat-dashboard.php5 package later on!
sudo yum remove php*
 
# add repos
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
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
# add repo for 3.2.7 and later
yum -y install epel-release
rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-6.rpm
 
 
# update yum repos
sudo yum update

CentOS 7.X

# If php5 is already installed and you want to use php7,just remove old version of php to avoid conflicts. If you want to use php5 you have to use the apiomat-dashboard.php5 package later on!
sudo yum remove php*
 
#add repos
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-7.rpm
sudo rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
sudo yum update

OpenSUSE 12

#remove old php5 packages
sudo zypper remove php*
 
#for openSUSE:
sudo zypper addrepo --no-gpgcheck http://download.opensuse.org/repositories/devel:/languages:/php:/php72/openSUSE_Leap_15.1/devel:languages:php:php72.repo
#for SUSE SLE
sudo zypper addrepo http://download.opensuse.org/repositories/devel:/languages:/php:/php72/SLE_12_SP4/devel:languages:php:php72.repo

OpenSUSE 15

#remove old php5 packages
sudo zypper remove php*
 
zypper addrepo --no-gpgcheck http://download.opensuse.org/repositories/devel:/languages:/php:/php72/openSUSE_Leap_15.1/devel:languages:php:php72.repo
sudo zypper refresh

Windows


PHP installation for windows is included in the .exe file. For more details look into section Installation below.

System requirements

The following instance configurations are recommended.

Size

CPU

Memory

Disk

Typical Cloud Instance Types

Small

(One Server)

2 core

4 GB RAM

300 GB

AWS: t2.medium

Azure: Standard_A2_V2

Medium

4 core

8 GB RAM

500 GB

AWS: c5.xlarge

Azure: Standard_A4_v2

Large

8 core

16 GB RAM

500 GB

AWS: c5.2xlarge

Azure: Standard_A8_v2

Installation

USERNAME, PASSWORD, and TOKEN values are provided per customer from ApiOmat.


Debian

Debian
# This package is needed to install from https repositories:
apt-get install apt-transport-https
 
# Install the repo key
wget -O - https://repo-int.apiomat.com/yambas/rest/web/Key/LIVE/apiomat-archive-keyring.asc | sudo apt-key add -
 
# Add the repository
echo "deb https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/deb ./" | sudo tee /etc/apt/sources.list.d/apiomat.list
 
# Update APT and install
apt-get update
apt-get install apiomat-dashboard
service aom-yambas start

Centos7/Oracle/RedHat

Centos7/Oracle/RedHat
# Add the repository
echo "[apiomat]
name=ApiOmat
baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/YAMBAS/rest/web/Repo/LIVE/rpm
gpgcheck=0
enabled=1" > /etc/yum.repos.d/apiomat.repo
 
# Install
yum update
yum --nogpgcheck --enablerepo=remi-php73 install apiomat-dashboard
 
service aom-yambas start

Centos6

Centos6
# Add the repository
echo "[apiomat]
name=ApiOmat
baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/YAMBAS/rest/web/Repo/LIVE/rpm
gpgcheck=0
enabled=1" > /etc/yum.repos.d/apiomat.repo
 
# Install
yum update
# add "--enablerepo=remi-php73" only for 3.2.7 and later versions
yum --nogpgcheck --enablerepo=remi-php73 install apiomat-dashboard
 
# for 3.2.7 and later, you can also make sure that 7.3 is installed by executing those two commands:
yum -y --enablerepo=remi-php73 install php
httpd -k restart
 
 
# starting yambas
service aom-yambas start

Suse 12

Suse 12
# Add the repository
zypper addrepo --no-gpgcheck https://repo.apiomat.com/YAMBAS/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
 
 
# Refresh zypper and install
zypper refresh
zypper --no-gpg-checks --non-interactive install apiomat-dashboard.suse
service aom-yambas start

Suse 15

Suse 15
# Add the repository
zypper addrepo --no-gpgcheck https://repo.apiomat.com/YAMBAS/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
 
# Refresh zypper and install
zypper refresh
zypper --no-gpg-checks --non-interactive install apiomat-dashboard.suse
 
# install suse 15 not matched php dependency
zypper --no-gpg-checks --non-interactive install php-json
service apache2 restart
 
service aom-yambas start

Docker Compose

Docker Compose
# Docker login
docker login -u <USERNAME> -p <PASSWORD>
 
# Store the following file and execute:
docker-compose -f dashboard.yml up
dashboard.yml
version: '3'
services:
consul:
image: library/consul
# Uncomment if you want to access consul container from outside of the docker network
# ports:
# - "8500:8500"
command: agent -dev -ui -client=0.0.0.0
mongo:
image: apiomat/mongo-conf:3.4
# Uncomment if you want to access the MongoDB container from outside of the docker network
# ports:
# - "27017:27017"
command: --smallfiles
yambas:
image: apiomat/yambas:<YAMBAS_VERSION>
# Uncomment if you want to access the YAMBAS container from outside of the docker network
# ports:
# - "8081:8081"
environment:
common_hosts_admin: http://localhost:8081
common_hosts_live: http://localhost:8000
common_hosts_staging: http://localhost:8000
common_hosts_test: http://localhost:8000
common_isEnterpriseInstallation: "true"
yambas_configEncryptionKey: '<encryptionKey>'
common_consul_url: http://consul:8500
common_consul_health_port: 8081
yambas_mongodb_hosts_default: mongo:27017
yambas_license_key: <licensekey>
depends_on:
- mongo
- consul
dashboard:
image: apiomat/alpine-dashboard:<DASHBOARD_VERSION>
environment:
common_hosts_admin : http://yambas:8081
# bind access to Dashboard on local port (default 8000)
ports:
- 8000:8000

Create first account

To connect to YAMBAS with above docker compose configuration, you need to create a SuperAdmin account by sending a POST request to /yambas/rest/initSuperAdmin with form parameters "email" and "password" once the containers started. 

e.G : curl -X POST http://localhost:8000/yambas/rest/initSuperAdmin -d "email=apinaut@apiomat.com&password=secret"
or wget: wget -qO- --post-data 'email=apinaut@apiomat.com&password=secret' http://localhost:8000/yambas/rest/initSuperAdmin

Kubernetes

Kubernetes

To obtain the latest manifest file, please contact the EASY ApiOmat support.

Helm

Helm
# Docker login
kubectl create secret docker-registry regcred \
 --docker-server=https://index.docker.io/v1/ \
--docker-username="<USERNAME>" \
 --docker-password="<PASSWORD>" \
--docker-email="<MAIL>"
 
# We are using helm to deploy the yambas replicaset
helm init
helm repo update
helm repo add apiomat https://apinautengmbh.github.io/helm/
helm fetch apiomat/apiomat-dashboard
# extract the archive (.tgz) and find the values.yml. Adjust the parameters as required.
helm install apiomat/apiomat-dashboard --name apiomat-dashboard --values values.yaml

Windows

Windows

  1. 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).

  2. 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.

  3. At the beginning of the setup you can choose an install path. The default one ("C:\Program Files\ApiOmat ") is fine. If you already had YAMBAS installed in the same directory, you will see a prompt saying that the folder already exists. You can install the Dashboard in the same directory.

  4. Next you have the choice to (de-)select some setup options, it's recommended to keep the defaults.

    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 note that Apache HTTP Server is selected by default, because it doesn't get installed by the YAMBAS installer. If you already installed Apache HTTP Server with the YAMBAS installer you can deselect it within the Dashboard installer. In that case some adjustments need to be made in the httpd.conf file. Please contact the support for further assistance.
    Info:     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."

  5. 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.

  6. When all scripts are finished :

    1. You can choose to start the service for Apache.

    2. You can also choose to open the Dashboard URL. It will prompt the installation UI which is further explained below in the Next steps section.

  7. After installation is finished, you need to make sure that a number of services are started. You may either run "services.msc" or open the task manager and click on the 'services' tab.
    If some of the following services are not active, you have to start them manually:

    1. "MongoDB" (required if MongoDB was installed as a service).

    2. "Apache".

Configuration


Linux and Windows

Linux and Windows

The following configuration files are provided:

%CONFIG_PATH/installPath

With the release 2.6.0 it's possible to set the installation path and backup path for Dashboard. Those paths are requested during installation. The data is then stored under %CONFIG_PATH/installPath. The installPath file has the following structure:


/etc/apiomat/installPathYambas
export APIOMAT_DASHBOARD=/opt/aom-dashboard3
export APIOMAT_DASHBOARD_ALIAS=/

%CONFIG_PATH/apiomat.yaml

The main configuration file, which contains all necessary information to start Dashboard in a single node environment.

General service configuration possibilities are described at the configurations main page.

The most common configuration keys are:

Key

Default

Explanation

dashboard_helpUrl

/docs

Help URL, can also be set to an external address

common_hosts_test

http://localhost:8080/

The public address for the test system, used e.g. in sdks or app-configuration

common_hosts_staging

http://localhost:8080/

The public address for the staging system, used e.g. in sdks or app-configuration

common_hosts_live

http://localhost:8080/

The public address for the live system, used e.g. in sdks or app-configuration

common_hosts_admin

http://localhost:8080/

Adress used by Dashboard to reach YAMBAS (Mandatory to communicate with YAMBAS instance, service name can be used as hostname here if running on the same docker network)

Docker

Docker

Environmental Variables

Required variables are printed in bold.

Key

Default

Explanation

DEBUG

false

Information about variable mapping is displayed

PROXY_TIMEOUT

300

AJP Proxy Timeout: Timeout between Dashboard and Yambas can be increased here.

ALIAS

/

Alias of virtual host

ALIAS_PROXY

/

Alias of AJP proxy host

dashboard_baseUrl

/

when using specific dispatcher mechanics (e.g. apiomat dispatcher) this option can be used to configure the base url,

if it's not configured, php will use the $_SERVER['HTTP_HOST'] variable automatically

dashboard_helpUrl

/docs

Help URL, can also be set to an external address

TIMEZONE

Europe/Berlin

Local timezone

dashboard_disableSSLChecks

false

Disable ssl checks of dashboard

dashboard_embeddedObjectsSupport

false

Hide embedded objects switch if set to false

common_hosts_admin

http://localhost:8080/

Adress used by Dashboard to reach YAMBAS (Mandatory to communicate with YAMBAS instance, service name can be used as hostname here if running on the same docker network)

common_hosts_live

http://localhost:8080/

The public address for the live system, used e.g. in sdks or app-configuration

common_hosts_staging

http://localhost:8080/

The public address for the staging system, used e.g. in sdks or app-configuration

common_hosts_test

http://localhost:8080/

The public address for the test system, used e.g. in sdks or app-configuration

ENV_MODE

PRODUCTION

DEVELOPMENT or PRODUCTION

common_analytics_internal


The internal address from which the analytics instance is available

common_analytics_public


The external address where the instance is available, used for sdks

dashboard_cacheEnabled


Enable cache of dashboard

dashboard_deployCheckInterval


Check interval of deploy

dashboard_curlRequestTimeout


Timeout of curl requests

common_consul_url


URL of Consul agent

dashboard_health_host


Hostname of dashboard which is accessible from Consul. (e.g. localhost), if there is no host given, the container will try to determine itself via the "hostname -i" shell command

common_consul_discovery_scheme

h


dashboard_health_port


Port of Dashboard which is accessible from Consul (e.g. 80)

common_consul_health_timeout


Timeout for health check of this service; defaults to 2 seconds.

common_consul_health_interval


Interval for health check of this service; defaults to 5 seconds. Should also be greater than the timeout.

common_consul_health_deregisterAfter


Consul removes the service itself after it has been critical for the specified time.

dashboard_health_contextPath


url alias of dashboard (e.g. /)

dashboard_health_scheme

http

the scheme of the URL from consul (common.consul.discovery.scheme will be overwritten by this value if it's defined)

dashboard_loglevel

"error, warning"

loglevel of dashboard. e.g. "error, warning, trace, info"

dashboard_serviceAddressCachingTime

60

caching time of internal service addresses

Logging


Linux

Linux

Logging is done to a separate logfile:

Linux
tail -f /opt/aom-dashboard3/site/apiomat/log/application.log

Docker

Docker

Please replace <DASHBOARD_CONTAINER_ID> with your running container ID. You can list your running containers using 'docker container list' command.

Docker
docker logs -f <DASHBOARD_CONTAINER_ID>

Kubernetes

Kubernetes

Please replace <DASHBOARD_CONTAINER_ID> with your running container ID. You can list your running container using 'kubectl get pods' command.

Kubernetes
kubectl logs -f <DASHBOARD_CONTAINER_ID>

Windows

Windows

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

  • 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 .\log -tail 100 -wait

Next steps