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 expired on 31.12.2018. PHP 7.3 (since Dashboard 3.4.1) or a PHP Version 7.4 <= x<= 8.1 (since Dashboard v3.8.1) should be installed instead!

Ubuntu

# Add repository for php7/8. 
sudo add-apt-repository ppa:ondrej/php -y
sudo apt-get update

Debian

# Add repository for php7/8
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

CentOS 7.X

# If php5 is already installed and you want to use php7/8,just remove old version of php to avoid conflicts. 
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

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
# for Dashboard before version 3.8.1
yum --nogpgcheck --enablerepo=remi-php73 install apiomat-dashboard
# for Dashboard starting with version 3.8.1 
yum --nogpgcheck --enablerepo=remi-php81 install apiomat-dashboard
 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.

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

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