. . .

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 expires on the 31.12.2018, so the dashboard php 5 installation package is deprecated since the 3.2 version. PHP 7.1 should be installed instead!

# 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
# 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
# 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
# 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
# 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
#remove old php5 packages
sudo zypper remove php*
 
#for openSUSE:
zypper addrepo --no-gpgcheck http://download.opensuse.org/repositories/devel:/languages:/php:/php71/openSUSE_Leap_42.3/devel:languages:php:php71.repo
#for SUSE SLE
sudo zypper addrepo http://download.opensuse.org/repositories/devel:languages:php/SLE_12/devel:languages:php.repo
#remove old php5 packages
sudo zypper remove php*
 
zypper addrepo --no-gpgcheck http://download.opensuse.org/repositories/devel:/languages:/php:/php71/openSUSE_Leap_42.3/devel:languages:php:php71.repo
sudo zypper refresh

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
# 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
# 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 install apiomat-dashboard
 
service aom-yambas start
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
# 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
service aom-yambas start
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
 
# 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 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:
# To use Dashboard as reverse proxy to YAMBAS
# YAMBAS rest endpoint will be accessible to http://localhost:<dashboard_bound_port>/yambas/rest
YAMBAS_EXTERNAL: yambas
YAMBAS_EXTERNAL_PORT: 10009
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
# Docker login
kubectl create secret docker-registry regcred \
 --docker-server=https://index.docker.io/v1/ \
--docker-username="<USERNAME>" \
 --docker-password="<PASSWORD>" \
--docker-email="<MAIL>"
 
# Store the following file and execute
kubectl apply -f dashboard.yml
dashboard.yml
---
# Source: apiomat-dashboard/templates/configmap.yaml
 
apiVersion: v1
kind: ConfigMap
metadata:
labels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
heritage: Tiller
release: release-name
name: release-name-apiomat-dashboard
data:
apiomat.yaml: |-
common:
audit:
contentEnabled: true
enabled: false
defaultOrganizationEmail: org@example.domain
emails:
admin: admin@example.domain
debug: true
footer: null
host: localhost
noreply: noreply@example.domain
port: 25
support: support@example.domain
useAuth: false
useSsl: false
useStarttls: false
hosts:
admin: http://yambas-service:8081
live: https://example.domain
staging: https://example.domain
test: https://example.domain
isEnterpriseInstallation: true
isWhitelabelInstallation: false
sendCustomerVerificationMailImmediately: false
superadminEmail: apinaut@example.domain
useSsl: false
dashboard:
helpUrl: /docs
installerFinished: true
monitoring: null
tools:
apiomatStudioMobile:
appLocation: https://repo.apiomat.com/yambas/rest/web/Tools/LIVE/studiomobile/app/3_2
templateLocation: https://repo.apiomat.com/yambas/rest/web/Tools/LIVE/studiomobile/template/3_2
yambas:
accessControlAllowOriginList: '*'
defaultModules: Basics
defaultModulesPerSystem: null
enableMultipleCSVImport: false
git:
conflictmode: branch
license:
key: QD3QD-DSP9F-GBPG6-DI2Y3-XQ5A7-VKQGA-A9JER-ZDI7W-GUIIG-ICQ4S-EMLJQ
limits:
maxCompileTimeInMinutes: 5
maxCronTime: 99999999
maxDataJsonKB: 1000
maxDataUploadMB: 200
maxHookCallDepth: 20
maxResourceCacheSizeKB: 10
maxResults: 10000
maxStringSizeOnExport: 100000
serverStartDeployTime: 60
unconfirmedMaxdays: 7
logTaskPeriodInSeconds: 30
mongodb:
authDB: admin
connections: 100
hosts:
default: <mongodb_statefulset1:27017>,<mongodb_statefulset2:27017>,<mongodb_statefulset3:27017>
live: <mongodb_statefulset1:27017>,<mongodb_statefulset2:27017>,<mongodb_statefulset3:27017>
staging: <mongodb_statefulset1:27017>,<mongodb_statefulset2:27017>,<mongodb_statefulset3:27017>
test: <mongodb_statefulset1:27017>,<mongodb_statefulset2:27017>,<mongodb_statefulset3:27017>
testConnectionTimeout: 5
userName:
default: apiomat
userPassword:
default: supersecretpassword
noSystemCache: false
oAuth2TokenValiditySeconds:
manuallySet:
access: 2592000
refresh: 604800
standard:
access: 604800
refresh: 2592000
planDefault: Basic
planTrialReminderDays: 30,20,10,5,3,2,1
sendCustomerVerificationMailImmediately: false
strictChecks: true
 
---
# Source: apiomat-dashboard/templates/service.yaml
kind: Service
apiVersion: v1
metadata:
name: release-name-apiomat-dashboard
labels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
release: "release-name"
heritage: "Tiller"
spec:
ports:
- name: http
port: 8000
protocol: TCP
type: NodePort
selector:
app: apiomat-dashboard
release: release-name
---
# Source: apiomat-dashboard/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
heritage: Tiller
release: release-name
name: release-name-apiomat-dashboard
spec:
replicas: 2
selector:
matchLabels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
release: release-name
template:
metadata:
labels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
release: release-name
spec:
imagePullSecrets:
- name: <regcred>
containers:
- name: apiomat-dashboard
image: docker.io/apiomat/dashboard:3.2.4
ports:
- containerPort: 8000
name: http
env:
- name: YAMBAS_EXTERNAL
value: "<yambas-service>"
- name: YAMBAS_EXTERNAL_PORT
value: "10009"
- name: DEBUG
value: "false"
- name: ENV_MODE
value: "PRODUCTION"
- name: USE_EXISTING_CONFIG
value: "true"
resources:
limits:
memory: 1Gi
requests:
memory: 512Mi
 
livenessProbe:
httpGet:
path: /site/login
port: 8000
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 6
readinessProbe:
httpGet:
path: /site/login
port: 8000
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 6
volumeMounts:
- name: config
mountPath: /etc/apiomat/apiomat.yaml
subPath: apiomat.yaml
imagePullPolicy: Always
securityContext:
capabilities: { }
privileged: false
volumes:
- name: config
configMap:
name: release-name-apiomat-dashboard
---
# Source: apiomat-dashboard/templates/ingress.yaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: release-name-apiomat-dashboard
labels:
app: apiomat-dashboard
chart: apiomat-dashboard-3.2.4
release: release-name
heritage: Tiller
spec:
rules:
- host: "example.domain"
http:
paths:
- path: /
backend:
serviceName: release-name-apiomat-dashboard
servicePort: http
 
---
# Source: apiomat-dashboard/templates/requirements.yaml
#dependencies:
#- name: apiomat-yambas
#version: 3.2.0
#repository: https://kubernetes-charts.storage.googleapis.com
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

  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

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

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.

YAMBAS_EXTERNAL_PORT

10009

Internal AJP port from YAMBAS. (This is mandatory if you want to use the Dashboard as reverse proxy to YAMBAS.)

ALIAS

/

Alias of virtual host

ALIAS_PROXY

/

Alias of AJP proxy host

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

YAMBAS_EXTERNAL

yambas

Address to YAMBAS. The service name can be used as hostname here if running on the same docker network. (This is mandatory if you want to use the Dashboard as reverse proxy to yambas.)

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. http://localhost)

dashboard_health_port

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

dashboard_health_timeout

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

dashboard_health_interval

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

dashboard_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. /)

Logging

Linux

Logging is done to a separate logfile:

Linux
tail -f /opt/aom-dashboard3/site/apiomat/log/application.log
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

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

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