. . .

[Explorer] Installation

Introduction

This page provides the steps to install and configure the ApiOmat microservice called "Explorer" for central UI of the services' REST endpoints. For further information about Explorer itself and its functionality please refer to its documentation.

Prerequisites


Open the following port in the firewall to other ApiOmat nodes:

  • 8094 (HTTP)

Installation of Consul is required!

Installation of AdoptOpenJDK is required when not using Docker!


System requirements

The following instance configurations are recommended.

Size

CPU

Memory

Disk

Typical Cloud Instance Types

All

2 core

512 MB RAM

500 MB

AWS: t2.medium





Azure: Standard_ B1MS

Installation

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


Debian/Ubuntu

Debian/Ubuntu
# 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 -y aom-explorer
service explorer start

Centos/Oracle/RedHat

Centos/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 -y --nogpgcheck install aom-explorer
service explorer start

Suse

Suse
# 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 aom-explorer
service explorer start

Docker Compose

Docker Compose
# Docker login
docker login -u <USERNAME> -p <PASSWORD>
 
# Store the following file and execute:
docker-compose -f explorer.yml up

explorer.yml:

version: '3'
services:
explorer:
image: apiomat/explorer:<VERSION>
command: --spring.cloud.consul.enabled=false
ports:
- "8094:8094"

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-explorer
# extract the archive (.tgz) and find the values.yml. Adjust the parameters as required.
helm install apiomat/apiomat-explorer --name apiomat-explorer --values values.yaml

Windows

Windows

  1. Download file: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/aom-explorer-<VERSION>.zip?token=<TOKEN> and unzip to installation folder

  2. Ensure that the path to your installed jdk\bin is set to the system-environment variable 'Path' (java.exe needs to be accessible for windows' system user!)

  3. Open administrative console and execute 

    Explorer-<VERSION>.exe install
    Explorer-<VERSION>.exe start

    to install as service and start afterwards.

    For a removal of the service, execute 

    Explorer-<VERSION>.exe uninstall

Configuration

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

This service has the following specific configuration values:

Name

Description

Example

explorer.excluded.services

comma-separated list of services to exclude the retrieval of the open api spec (f.i. if they're not providing a spec)

"consul,nomad,instructor"

explorer.yambas-tomcat-fallback-url

When Explorer is deployed as WAR inside the same Tomcat as yambas, this is the base URL for reaching yambas (depends on Tomcat's settings.xml).

By default (when no value is set here) three URLs are tried:

  1. "http://localhost:8080"

  2. "http://localhost:8081" (works when using our Docker images)

  3. request.getScheme( ) + "://" + request.getServerName( ) + ":" + request.getServerPort( )

http://localhost:8000

explorer.basepath

You can configure the basepath, if explorer and other services are available under a non-root basepath (f.i. if all services are available under "/dispatcher"), MUST start with "/"

/dispatcher

When Explorer is deployed as WAR inside the same Tomcat as YAMBAS, you can either change the configuration in "<TOMCAT_PATH>/webapps/explorer/WEB-INF/classes/application.yml" or, especially when running in Docker, via environment variable, for example "EXPLORER_YAMBAS-TOMCAT-FALLBACK-URL".

Logging


Linux

Linux

Logging is done to a separate logfile:

tail -f /var/log/apiomat/explorer/explorer.log

Docker

Docker

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

docker logs -f <EXPLORER_CONTAINER_ID>

Kubernetes

Kubernetes

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

kubectl logs -f <EXPLORER_CONTAINER_ID>

Windows

Windows

All logs are written to Event manager.

Next steps

Install further microservices.