. . .

YAMBAS Installation

Introduction

YAMBAS is the core component of ApiOmat, containing all data modelling, generation and module functionality. To get a deeper dive into the main parts of ApiOmat, visit the overview page.

Prerequisites



Open the following ports in the firewall:

Port

Transport

Service

Host

Client

8080

TCP

YAMBAS

Application Server

Outside World

5701

TCP

Hazelcast

Application Server

Application Server

2022

TCP

FTP/Webhosting Module

Application Server

Outside World

2300

TCP

FTP/Webhosting Module

Application Server

Outside World

123

UDP

NTP (Windows only)

All

Outside World

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/Ubuntu

# This package is needed to install from https repositories:
apt-get install apt-transport-https
 
# Install the repo key
wget -O - https://repo.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-yambas
service aom-yambas start

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 update
yum --nogpgcheck install apiomat-yambas
 
service aom-yambas start

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 apiomat-yambas
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 yambas.yml up

yambas.yml:

version: '3'
services:
consul:
image: library/consul
# Uncomment if you want to access the 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 container from outside of the docker network
# ports:
# - "27017:27017"
command: --smallfiles
yambas:
image: apiomat/yambas:<VERSION>
ports:
- "8081:8081"
environment:
common_hosts_admin: https://localhost:8081
common_hosts_live: https://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

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

Windows

Windows

Upgrade

If upgrading from a previous ApiOmat version, backup all changes and files which were modified manually in the Apache Tomcat subfolders (e.g. shared/lib contents), because all data will be overwritten in the automatic setup.


  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_yambas_setup_<VERSION>.exe"

  2. Run the setup file. 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.

  4. You can then change the following options, it is recommended to keep the defaults.

    1. "Dependency installation": You can (de-)select third party software like Java in case it's already installed.

    2. "Dependency configuration": Configures Apache, Tomcat etc.

    3. "System configuration": Configures NTP, Firewall etc.

    4. "ApiOmat configuration": Copies ApiOmat config files

    In any case, the Tomcat web application files (.war) get installed to the Tomcat webapp directory.
    Please also note that Apache HTTP Server is deactivated by default, because it gets installed by the Dashboard installer. You should only choose to install Apache HTTP Server with the yambas installer if you want to run yambas and Dashboard on different servers.

  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 with a GUI. For example the Tomcat installation works with the Tomcat installer GUI. The guide contains info on what options to select in the GUI. Please pay attention to every point, for example you shouldn't install Tomcat to its default directory, but to "C:\tomcat8" instead. Also please note that the Tomcat installer GUI should launch in the background, so when the guide is shown, you have to click on the Tomcat installer in the Windows taskbar.


Last steps:

6. When all scripts are finished, there are two different ways your installation will end (depending on your Windows Version) :

a. you will be asked to restart your PC, which is an automatic Windows Feature to clean up temporary settings of the installation. In fact, this is not needed after installing ApiOmat Yambas, so you may select 'no restart'.
b. you will be asked to autostart the services for Tomcat and Apache after installation and visit some URLs like Apidocs.
Note 1: Even with selected options this sometimes does not work due to some Windows issues, so pay special attention to the next steps.
Note 2: These URLs open on port 8080 because the Apache HTTP Server and the proxy settings are not installed by default.

7. After you made your choice 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" (if it was installed as service)

    2. "Apache" (if Apache Proxy service was installed. Possibly it is not listed in the service tab on all Windows Versions because the Apache HTTP Server is not installed by default)

    3. "Tomcat8" (wait about 2 minutes for Tomcat to launch ApiOmat Yambas)

  2. Hint: If you have problems regarding failing file access of the Tomcat service, double-check the "Log On As" parameter in services.msc. By the Tomcat installer this is automatically set to "NT Authority\LocalService" which may not be available in newer Windows Versions and Hyper-V Machines. If that happen we recommend to change the "Log On As" property to "LocalSystem".

8. Visit (or refresh if selected in step 6b) the first ApiOmat pages to initialize the SuperAdmin account:

a. Visit yambas REST test URL to check if ApiOmat Yambas is available: https://localhost:8080/yambas/rest
b. Visit apidocs to create the SuperAdmin account (See Next Steps for detailed information): http://localhost:8080/apidocs
Tip: If you are going to install ApiOmat Dashboard too, you may skip this step to configure the whole system with the Dashboard's installer servlet later and set your SuperAdmin account, too.
c. Visit documentation to get started with ApiOmat: http://localhost:8080/docs

Create first accounts

To finish installation and make YAMBAS accessible, you have to create a first account - see Next Steps

Please note that YAMBAS won't register by Consul until first account has been created.

Configuration


Linux and Windows

Linux and Windows

The following configuration files are provided:

%CONFIG_PATH/installPathYambas (only Debian)

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

export APIOMAT_YAMBAS_BACKUP=/home/my-backup-apiomat
export DEFAULT_BACKUP_PATH_YAMBAS=/srv/restoremodule
export INSTALL_ROOT_PATH_YAMBAS=/opt/my-apiomat
export DEFAULT_INSTALL_PATH_YAMBAS=/opt
export DEFAULT_INSTALL_SUB_PATH_YAMBAS=/aom-yambas

APIOMAT_YAMBAS_BACKUP points to the directory apiomat stores its backups (default=/srv/restoremodule). INSTALL_ROOT_PATH_YAMBAS points to the root directory where Apache Tomcat, JDK and ApiOmat Yambas itself will be stored. After installation YAMBAS will be available under /<customizedRootPath>/aom-yambas.

%CONFIG_PATH/aom-yambas

If consul was NOT installed, add the following line between one of the JAVA_OPTS=... lines:

JAVA_OPTS="${JAVA_OPTS} -Dspring.cloud.consul.enabled=false"


%CONFIG_PATH/apiomat.yaml

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

The most common configuration keys are:

Key

Default

Explanation

common.hosts.admin

https://localhost:8080

The internal address yambas and the dashboard uses to reach itself

common.hosts.live

https://localhost:8080

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

common.hosts.staging

https://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

common.superadminEmail

apinaut@apiomat.com

If you change the SuperAdmin credentials in the Dashboard, the credentials below must match them

common.defaultOrganizationPassword


The default organization's password; gets generated automatically

common.consul.url

http://localhost:8500

URL of the running Consul instance

common.consul.discovery.scheme

http

Set to "https" if YAMBAS should communicate with Consul via HTTPS

common.consul.health.timeout

120

Timeout for health check of YAMBAS

common.consul.health.interval

30

Interval for health check of YAMBAS

common.consul.health.port

8080

Port of YAMBAS which is accessible from Consul

common.consul.health.host


Hostname of YAMBAS which is accessible from Consul

common.securePingEndpoint

false

TRUE if sensitive information (YAMBAS version, IP address and port) should not be returned when an unauthenticated (guest) request is sent to the ping endpoint.
Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

yambas.license.key


The ApiOmat license key

yambas.mongodb.hosts.default

localhost:27017

Default Mongodb host URLs (comma separated if multiple), may have a port after each value,
e.g. "localhost:27017", otherwise the default port 27017 will be used

yambas.mongodb.hosts.live


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on LIVE system
If this value is not present, the values from default will be used

yambas.mongodb.hosts.staging


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on STAGING system
If this value is not present, the values from default will be used

yambas.mongodb.hosts.test


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on TEST system
If this value is not present, the values from default will be used

yambas.mongodb.userPassword.default


Default password for each stage, if no value present, the default will be used if the password is an empty string, no auth will be used!

yambas.mongodb.userName.default

apiomat

The username to use for a connection to the database

yambas.configEncryptionKey


The configEncryptionKey used for encryption of e.g. module configuration passwords. It gets overwritten by a randomly generated value during installation. Should be 16, 24 or 32 characters long. Other lengths get trimmed to the next lower valid length. After installation, when this value is the randomly generated one, it must not be changed when updating yambas!

yambas.strictMode

false

When strictMode is enabled the following settings will be done internally:

  • the old static data endpoints without dependency to a dataModel object are disabled, which means that the corresponding hook methods will always be called

  • newly created classes will have restrictedResourceAccess set to true

  • newly created classes will have ACL Roles set to AppAdmin

Furthermore the following Module default configuration will be applied for new applications:

  • the BasicModule configuration "USERS_CAN_SEE_EACH_OTHER" is set to "false"

  • the BasicModule configuration "CREATE_USER_ROLE" is set to "AppAdmin"

  • the WebhostingModule configuration "WEBHOSTING_READ_ROLE" is set to "AppAdmin"

  • the PushModule configuration "ALLOW_USERS_TO_SEND_PUSH" is set to "false"

yambas.noModuleDbLog

false

if set to true, the native module logs are not written to the database. this means that the logs won't be shown in the log console within the dashboard, but this may increase performance. It may not be necessary to store the logs into the database if logging systems like graylog are used. Available since YAMBAS versions 3.6.2, 3.7.1 and 3.8.0

spring.zipkin.baseUrl


If defined, traces are sent to a Zipkin installation


Further configuration possibilities are described in the %CONFIG_PATH/apiomat.yaml.example file.

Docker

Docker

Environmental Variables

Required variables are printed in bold.

Key

Default

Explanation

DEBUG

false

Information about variable mapping is displayed.

HAZELCAST_DISCOVERY

Discovery disabled

empty → Discovery is disabled

consul → Discovery via Consul (the following variables must be set for this)

multicast → Discovery via multicast

DISABLE_HAZELCAST_MULTICAST


Disable multicast in Hazelcast (Multicast is also disabled with the other options before, except with the option HAZELCAST_DISCOVERY ="multicast")

HAZELCAST_NEARCACHE_ENABLE

false

The nearcache of hazelcast (used for internal caching of Customers and Backends) was enabled in versions prior to 3.1.3 by default, but may lead to inconsistencies when reading the data. Therefore we disabled it by default in versions after 3.1.3 and 3.2.0. To enable it again, set this to true

HAZELCAST_USERNAME

dev

Username for Hazelcast

HAZELCAST_PASSWORD

dev

Password for Hazelcast

HAZELCAST_GROUP

yambas

Group for Hazelcast

HAZELCAST_NETWORK_XML


Deposit your own network xml

HAZELCAST_XML


Deposit your own hazelcast xml

PREFERRED_HAZELCAST_INTERFACE_HOST

IP of first network Yambas connected to

Only needed if running one Yambas instance in multiple Docker networks. Passes an IP address Yambas has in one of the networks which should be reachable by Hazelcast. Click here for more information.

PREFERRED_CONSUL_HEALTH_CHECK_HOST

IP of first network Yambas connected to

Only needed if running one Yambas instance in multiple Docker networks. Passes an IP address Yambas has in one of the networks which should be reachable by Consul. Click here for more information.

LOG4J_LEVEL_HAZELCAST

error

trace, warn, info, error

LOG4J_LEVEL_JERSEY

error

trace, warn, info, error

LOG4J_LEVEL_MONGODB

error

trace, warn, info, error

LOG4J_LEVEL_APIOMAT

error

trace, warn, info, error

GRAYLOG_HOST


If set, logging to graylog instance on the given host name will be activated in log4j.xml file

WAIT_FOR_MONGODB

false

true → wait for 10 seconds

DEBUG_PORT


Start yambas with remote debugging enabled on the defined debug port

JAVA_MAXRAMPERC


Set maximum JVM heap size as a percentage of total memory. Can be a double, e.g. 37.5. If not set, JAVA_XMS and JAVA_XMX will be used instead. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JAVA_XMS

1024m

Set the initial and minimum Java heap size. Only used if JAVA_MAXRAMPERC is not set.

JAVA_XMX

1024m

Set the maximum Java heap size. Only used if JAVA_MAXRAMPERC is not set. Note: has to be equal or higher than XMS
Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JAVA_THP

false

If set to true, the JVM will use Transparent Huge Pages for memory. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JAVA_CMSGC

false

If set to true, the Concurrent Mark Sweep garbage collector will be used instead of the default G1 collector. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JMX

off

Can be set to local or rmi to enable local or remote JMX management and monitoring, respectively. For the latter, you will also need to provide the hostname and password. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JMX_HOST


Hostname for remote JMX. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

JMX_PASS


Password for remote JMX. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

common_hosts_admin

http://localhost:8080

The internal address yambas and the dashboard uses to reach itself

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

common_consul_url

http://localhost:8500

URL of Consul agent

common_consul_discovery_scheme

http

Set to "https" if YAMBAS should communicate with Consul via HTTPS

common_consul_health_timeout

30

Timeout for health check of YAMBAS

common_consul_health_port

8081

The health check port matches the internal port of YAMBAS. If the YAMBAS port is exposed externally on a different port, adjust this health check port accordingly. Configurable since YAMBAS versions: 3.5.3. and 3.6.0.

common_consul_health_host


Internal hostname of YAMBAS; gets determined automatically

common_consul_health_registrationCheckInterval

0

Interval in minutes for scheduled job to check if YAMBAS is (still) registered to Consul and re-register it if not.

Job is deactivated by default - set a positive integer to activate it. Available since YAMBAS versions 3.5.2 and 3.6.0.

common_defaultOrganizationEmail

org@apiomat.com

The default organization's email address

common_defaultOrganizationPassword


The default organization's password; gets generated automatically

common_sendCustomerVerificationMailImmediately

false

Sends the verification emails immediately

common_superadminEmail

apinaut@apiomat.com

If you change the SuperAdmin credentials in the Dashboard, the credentials below must match them

common_emails_noreply

noreply@apiomat.com

The noreply-email address

common_emails_support

support@apiomat.com

The support-email address (e.g. used as sender for "forgot password"-requests)

common_emails_admin

admin@apiomat.com

The email's sender address ("from") used to send admin emails

common_emails_footer


The message footer for emails if not sent over mandrill

common_emails_debug

false

Debug option to print verbose information during email sending

common_emails_host


Hostname of the SMTP server

common_emails_user


Username if authentication on SMTP server is necessary

common_emails_password


Password if authentication on SMTP server is necessary

common_emails_port


Port of the SMTP server

common_emails_useAuth

false

TRUE if authentication is needed in SMTP server

common_emails_useSsl

false

TRUE if SSL connection should be used

common_emails_useStarttls

false

TRUE if STARTTLS should be used

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

common_securePingEndpoint

false

TRUE if sensitive information (YAMBAS version, IP address and port) should not be returned when an unauthenticated (guest) request is sent to the ping endpoint. Available since YAMBAS versions 3.3.3, 3.4.2, 3.5.1 and 3.6.0.

audit_enabled

false

Enables the audit-feature

audit_contentEnabled

false

Enables writing the create/update data to the log

yambas_license_key


The ApiOmat license key

yambas_mandrillApiKey


Mandrill API key - only needed if you want to send customized emails via Mandrill

yambas_yambasWebappDir


The path to WebAppDir of yambas, used to set the read-FilePermission

yambas_noSystemCache


Caches the cluster-urls internally in a map (during lifetime of yambas)

yambas_enableMultipleCSVImport

false

Enables multiple CSV imports for the same resource at a time

yambas_defaultModules

Basics

Comma separated list of modules to attach to all apps by default

yambas_defaultModulesPerSystem_live


Comma separated list of modules to attach to all apps by default for the live system

yambas_defaultModulesPerSystem_staging


Comma separated list of modules to attach to all apps by default for the staging system

yambas_defaultModulesPerSystem_test


Comma separated list of modules to attach to all apps by default for the test system

yambas_accessControlAllowOriginList

*

You can set a list of URIs that will be the only allowed origins when CORS requests get received. E.g.: "http://localhost, http://some.host, https://other.secure.domain, file://"

"*" allows all origins (but must be valid URIs). "none" or an empty value allows NO CORS requests.

yambas_allowedHostHeaders


Comma separated list of allowed hosts to prevent host header attacks. If the allowed host headers is not set or empty (default) every host header will be accepted by YAMBAS.

yambas_logTaskPeriodInSeconds

30

The time between one LogSaveTimer (for async save of logs in native modules) start and another in seconds

yambas_cronThreads

10

The number of threads being used for executing CRON hooks. Note: For a CRON hook to be executed in a new thread at all, the module must be configured with "runCronInNewThread = true" in its "@Module" annotation. Otherwise the hooks get executed by one single CRON timer thread, one after another.

yambas_useOldClassloader

false

Use of old classloader behaviour

yambas_cacheResourcesInClassloader

true

Cache already requested resource files of the module internally, size can be adjusted with the property yambas.limits.cacheResourcesInClassloader

yambas_mongodb_hosts_default

localhost:27017

Default Mongodb host URLs (comma separated if multiple), may have a port after each value,
e.g. "localhost:27017", otherwise the default port 27017 will be used

yambas_mongodb_hosts_live


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on LIVE system
If this value is not present, the values from default will be used

yambas_mongodb_hosts_staging


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on STAGING system
If this value is not present, the values from default will be used

yambas_mongodb_hosts_test


The Mongodb host URLs (comma separated if multiple) to use for a connection to the database on TEST system
If this value is not present, the values from default will be used

yambas_mongodb_userPassword_default


Default password for each stage, if no value present, the default will be used
if the password is an empty string, no auth will be used!

yambas_mongodb_userPassword_live


The user password to use for a connection to the database for LIVE system
If this value is not present, the values from default will be used

yambas_mongodb_userPassword_staging


The user password to use for a connection to the database for STAGING system
If this value is not present, the values from default will be used

yambas_mongodb_userPassword_test


The user password to use for a connection to the database for TEST system
If this value is not present, the values from default will be used

yambas_mongodb_userName_default

apiomat

The default username to use for a connection to the database

yambas_mongodb_userName_live

apiomat

The username to use for a connection to the database for LIVE system
If this value is not present, the values from default will be used

yambas_mongodb_userName_staging

apiomat

The username to use for a connection to the database for STAGING system
If this value is not present, the values from default will be used

yambas_mongodb_userName_test

apiomat

The username to use for a connection to the database for TEST system
If this value is not present, the values from default will be used

yambas_mongodb_authDB

admin

The auth database to use for the authentication, defaults to "admin"

yambas_mongodb_connections


Number of connections one mongodb-client will establish

yambas_mongodb_binPath


Path to binary folder of mongodb, used for RestoreModule:

yambas_mongodb_dumpPath


Path where to dump the mongodb database of an app, used for RestoreModule;

yambas_mongodb_testConnectionTimeout

5

On startup, there is an additional checkup whether the database is available. This check has a 5 second timeout set by default. If there is no response from the database after that time, Yambas responds to any request with the related errormessage. In most cases these 5 seconds should be enough for the connection timeout, but you can adjust it here, if the connection needs more time. Note that the timeout is only set for the test connection. The regular clients use the default timeouts.

yambas_ftp_keystore_path


Path and password to keystore used by SFTP server

yambas_ftp_keystore_password


Password of keystore

yambas_ftp_port

2021

Port of FTP server

yambas_ftp_passivePorts

2300

The passive ports to use, may be a single port, e.g. "2300", multiple comma-separated "2300,2301", port range e.g. "2300-2305" (without end-port means all ports over ...), or a combination, e.g. "2300,2301,2400-"

yambas_limits_maxCronTime

Long.MAX_VALUE

Maxmum number of milliseconds a cron task execution is allowed to take

yambas_limits_maxResults

1000

The maximum number of items to be included in the result of getAll requests;

yambas_limits_maxCompileTimeInMinutes

5

The maximum number of minutes which is allowed for a module to compile

yambas_limits_maxStringSizeOnExport

100000

The maximum size of strings to be exported using CSV or XML export;

yambas_limits_maxDataJsonKB

1000

The maximum KB size of static data (e.g. images) which should be returned directly in JSON data

yambas_limits_maxDataUploadMB

200

The maximum data size for uploads in MB (with 1 MB = 1,000,000 Bytes)

yambas_limits_maxHookCallDepth

20

The maximum depth in hook method calls

yambas_limits_maxResourceCacheSizeKB

10

Maximum size of a file in kb to be put in the resource cache (only takes effect if yambas.cacheResourcesInClassloader is enabled)

yambas_oAuth2TokenValiditySeconds_standard_access

604800

Value in seconds

yambas_oAuth2TokenValiditySeconds_standard_refresh

2592000

Value in seconds

yambas_oAuth2TokenValiditySeconds_manuallySet_access


Value in seconds

yambas_oAuth2TokenValiditySeconds_manuallySet_refresh


Value in seconds

yambas_configEncryptionKey


The configEncryptionKey used for encryption of e.g. module configuration passwords. It gets overwritten by a randomly generated value during installation. Should be 16, 24 or 32 characters long. Other lengths get trimmed to the next lower valid length. After installation, when this value is the randomly generated one, it must not be changed when updating yambas!

yambas_git_conflictmode

branch

Behaviour how to react on a conflict in git (changes in dashboard and repository at the same time),
may be either "branch" (create a branch with dashboard changes) or "force" (force-push changes to current branch)

yambas_strictMode

false

When strictMode is enabled the following settings will be done internally:

  • the old static data endpoints without dependency to a dataModel object are disabled, which means that the corresponding hook methods will always be called

  • newly created classes will have restrictedResourceAccess set to true

  • newly created classes will have ACL Roles set to AppAdmin

Furthermore the following Module default configuration will be applied for new applications:

  • the BasicModule configuration "USERS_CAN_SEE_EACH_OTHER" is set to "false"

  • the BasicModule configuration "CREATE_USER_ROLE" is set to "AppAdmin"

  • the WebhostingModule configuration "WEBHOSTING_READ_ROLE" is set to "AppAdmin"

  • the PushModule configuration "ALLOW_USERS_TO_SEND_PUSH" is set to "false"

spring_zipkin_baseUrl


If defined, traces are sent to a Zipkin installation

Kubernetes

Kubernetes

We have a separate Docker entrypoint script for working with Kubernetes.
To use this script instead of the regular entrypoint script, set the environment variable USE_K8S to true (default is false).

Please note that when using the K8S entrypoint script, there are several differences in configuration compared to the regular entrypoint script.
The most significant is that this script does not write into configuration files, so you can use your own existing files instead of having to set everything via environment variables.
To use your own configuration files, set the environment variable USE_EXISTING_CONFIG to true (default is false) and use a Kubernetes ConfigMap containing the following files:

  • apiomat.yml

  • hazelcast-k8s.xml

  • log4j2.xml (unless Graylog is being used for logging - see below - in which case the file should be called log4j-gelf-k8s.xml instead)

  • logging.properties

  • passwordpolicy.json

  • security.policy

The ConfigMap must be mounted to the directory /etc/apiomat of the YAMBAS container.

Since the K8S entrypoint script does not write to configuration files, the following environment variables have no effect when using it:

  • HAZELCAST_DISCOVERY

  • DISABLE_HAZELCAST_MULTICAST

  • HAZELCAST_NEARCACHE_ENABLE

  • HAZELCAST_USERNAME

  • HAZELCAST_PASSWORD

  • HAZELCAST_NETWORK_XML

  • HAZELCAST_XML

  • PREFERRED_HAZELCAST_INTERFACE_HOST

  • PREFERRED_CONSUL_HEALTH_CHECK_HOST

  • LOG4J_LEVEL_HAZELCAST

  • LOG4J_LEVEL_JERSEY

  • LOG4J_LEVEL_MONGODB

  • LOG4J_LEVEL_APIOMAT

  • GRAYLOG_HOST


There are also several new environment variables that only work with the K8S script:

Key

Default

Explanation

USE_CONSUL

true

If set to false, usage of Consul will be disabled.

GRAYLOG

false

If set to true, Graylog will be used for log management. If you are using your own configuration files, make sure to get the file name correct as mentioned above.

GELF_PROTOCOL


Protocol to use for Graylog, e.g. udp or tcp. Required when GRAYLOG is true.

GELF_HOST


Host of the Graylog server. Required when GRAYLOG is true.

GELF_PORT


Port of the Graylog server. Required when GRAYLOG is true.

GELF_ORIGIN


Origin of GELF messages (optional).

Logging


Linux

Linux

Logging is done to a separate logfile:

tail -f /var/log/apiomat/yambas/catalina.out

Docker

Docker

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

docker logs -f <YAMBAS_CONTAINER_ID>

Kubernetes

Kubernetes

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

kubectl logs -f <YAMBAS_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:\tomcat8\logs ("CONSOLE" appender / standard output logs here)

  • C:\Users\YourUser\AppData\Local\ApiOmat\logs ("FILE" appender logs here)

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 .\catalina.out -tail 100 -wait

First Steps

Create SuperAdmin
In order to use ApiOmat you first need to create a SuperAdmin account by sending a POST request to /yambas/rest/initSuperAdmin with form parameters "email" and "password" (note: you should change the example values).

After that YAMBAS will re-initialize itself automatically so you will be able to use all available REST end points to interact with YAMBAS.


OnPremise

OnPremise

with curl:

curl -X POST http://localhost:8080/yambas/rest/initSuperAdmin -d "email=apinaut@apiomat.com&password=secret"

or using wget:

wget -qO- --post-data 'email=apinaut@apiomat.com&password=secret' http://localhost:8080/yambas/rest/initSuperAdmin

Docker

Docker

At first, connect into your container. Please replace <YAMBAS_CONTAINER_ID> with your running container ID. You can list your running container using 'docker container list' command.

docker exec -it <YAMBAS_CONTAINER_ID> sh

And then, initialize the SuperAdmin by doing the following request (change the values for email and password according to your needs):

wget -qO- --post-data 'email=apinaut@apiomat.com&password=secret' http://localhost:8081/yambas/rest/initSuperAdmin

Kubernetes

Kubernetes

At first, connect into your container. Please replace <YAMBAS_CONTAINER_ID> with your running container ID. You can list your running container using 'kubectl get pods' command.

kubectl exec -it <YAMBAS_CONTAINER_ID> -- sh

And then, initialize the SuperAdmin by doing the following request (change the values for email and password according to your needs):

wget -qO- --post-data 'email=apinaut@apiomat.com&password=secret' http://localhost:8081/yambas/rest/initSuperAdmin

Apidocs

Apidocs

Go to http://localhost:8080/apidocs and use the listed rest endpoint to create a SuperAdmin account (change localhost to the host of your YAMBAS instance)



Next Steps