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:

Developer Dashboard
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"

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

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

Graphical installer:
After Dashboard installation open http://<yourHost>/dashboard/install in your browser and follow the steps in this installer tool to get ApiOmat configured automatically. This installation is fully described in Graphical installer that will assist you to set up basic configuration.
Configure Proxy / Loadbalancer

Dashboard Installation

Introduction

Prerequisites

Install PHP

System requirements

Installation

Configuration

%CONFIG_PATH/installPath

Environmental Variables

Logging

Next steps

Search results