@atlas-engine/admin_domain.application.minimal

AtlasEngine Admin Domain Minimal Server

Server application for providing remote access to the Admin Domain.

Currently supports http.

What are the goals of this project

The goal is to provide a ready-to-use environment for utilizing the AtlasEngine's Admin Domain.

This application expects a Runtime domain to be reachable at http://localhost:9000. Also, a Core Domain must be reachable at http://localhost:8400.

You can change the addresses in the config/<NODE_ENV>/repositories/runtime_repository.json config file.

A note on the tests

There is currently no mock for the admin_domain.repository.http package, but one will be added soon.

If you want to run the tests, you must ensure that the Runtime Domain Application running at http://localhost:9000 has its claim checks deactivated! The same goes for the Core Domain Application running at http://localhost:8400.

Also, you should avoid using productive Core- & Runtime- Applications for this, since the tests will be writing a lot of stuff the databases.

Table of contents

• Requirements
• Setup
  • Using npm
  • Using pre-build sources
• Starting the AtlasEngine AdminDomain Server
  • Global Routes
  • Switching the database
  • Customized Configuration
• Embedding the AtlasEngine AdminDomain Server into another application
  • Parameters
• Starting the AtlasEngine AdminDomain Server on system boot
  • macOS
  • Windows
• Application Files
• Authors

Requirements

• Node >= 10.15.0
• Python 2.7.x

Setup

Using npm

Install the application as a global npm package:

npm install -g @atlas-engine/admin_domain.application.minimal

Note: If you are experiencing problems during installation on Windows, you can try installing the Windows Build Tools and run the installation command again.

Also make sure that you run the command shell as Administrator.

Using pre-build sources

We provide ready-to-use sources with all our GitHub releases and pre-releases.

These are stored in a .tar.gz archive (for macOS and Linux) and a .zip file (for windows).

All sources have been fully installed and build.

You only need to download and unpack them and you are good to go.

The linux sources have been build on an ubuntu machine, but they should work on any other distribution as well.

NOTE:

The sources were build with NodeJS v10.

If you are using a different major NodeJS version (i.e. v11 or higher), you may encounter errors such as this:

2019-12-04T13:00:43.421Z - error: [atlasengine:server:startup] Error:  Error: Please install sqlite3 package manually

If that is the case, you will need to run npm rebuild, before you can use the sources.

Starting the AtlasEngine AdminDomain Server

You can start the application with the following command:

atlas-engine

When started, the AtlasEngine is available at

http://localhost:8200.

Note: If you're on Windows and the command atlas-engine can not be found, please make sure your PATH is set correctly.

Global routes

The AtlasEngine exposes a number of global HTTP routes, which you can use to get general information about the application.

These routes include:

• http://localhost:8200/ - Base route to get basic details about the AtlasEngine
• http://localhost:8200/atlas_engine - Same as above
• http://localhost:8200/security/authority - Returns the address of the authority the AtlasEngine uses to perform claim checks
• http://localhost:8200/atlas_engine/security/authority - Same as above

You might wonder why we use two routes for each UseCase.

The reason is simple: Let's say you want to embed your AtlasEngine into another web application. Usually, you'd want to use routes like http://localhost:8200/ for your own purposes and not have it expose information about any embedded service (which is what the AtlasEngine would be in this instance).

BPMN Studio uses these global routes to identify remote AtlasEngines to connect to. The route http://localhost:8200/atlass_engine ensures that the studio can do so, even if http://localhost:8200/ is reserved by your application.

In other words: These routes allow you to access an embedded AtlasEngine through BPMN Studio.

Note: See the Embedding instructions section on how to prevent the AtlasEngine from using / and /security/authority.

Switching the database

By default, the AtlasEngine will use SQLite as its database.

The corresponding files will be placed in the databases directory mentioned in the Application Files section.

If you want to use a different database, you must provide a NODE_ENV parameter at startup:

NODE_ENV=postgres atlas-engine

We provide presets for sqlite, postgres and mysql:

• Configuration for mysql repositories
• Configuration for postgres repositories
• Configuration for sqlite repositories

But you can use any other name for your config environment as well. develop, production, etc. will work just fine, as long as the settings are valid.

If you want to setup your own config environment, you can use one of the configs linked above as a template.

Note: Using MySQL or Postgres requires an instance of the respective database to be running and accessible!

Customized Configuration

By default, the server will use a set of configurations located within an integrated config folder.

If you wish to provide your own set of configurations, you can do so by setting the following environment variables prior to startup:

• CONFIG_PATH - The path to your configuration folder
• NODE_ENV - The name of the environment to use

NOTE: The path in CONFIG_PATH must be absolute.

Also, each environment must have its own configuration folder.

See here for an example on how a config must be structured.

Make sure you provide settings to all config sections listed there!

Example:

Let's say you want to store your configs in your local home folder, in a subfolder named admindomain and the environment you wish to use is named production.

Your configs must then be located in the following path:

• macOS: /Users/{{YOUR_USERNAME}}/admindomain/production
• Linux: /home/{{YOUR_USERNAME}}/admindomain/production
• Windows: C:\Users\{{YOUR_USERNAME}}\admindomain\production

You would need to provide the following environment parameters to access this config:

• NODE_ENV: production
• CONFIG_PATH:
  • macOS: /Users/{{YOUR_USERNAME}}/admindomain
  • Linux: /home/{{YOUR_USERNAME}}/admindomain
  • Windows: C:\Users\{{YOUR_USERNAME}}\admindomain

The full start command will then look like this:

• macOS: CONFIG_PATH=/Users/{{YOUR_USERNAME}}/admindomain NODE_ENV=production atlas-engine
• Linux: CONFIG_PATH=/home/{{YOUR_USERNAME}}/admindomain NODE_ENV=production atlas-engine
• Windows: CONFIG_PATH=C:\Users\{{YOUR_USERNAME}}\admindomain NODE_ENV=production atlas-engine

Embedding the AtlasEngine AdminDomain Server into another application

The AtlasEngine AdminDomain Server is published at npm under the name @atlas-engine/admin_domain.application.minimal.

You can add it to your package.json like any other npm package.

To start the server, you need to run this command once from inside your application:

import * as AtlasEngine from '@atlas-engine/admin_domain.application.minimal';

await AtlasEngine.launch(args);

Parameters

The launch function takes an object with the following optional parameters:

• workDir: A path to where the server will store its working data (i.e. 'workspace'). The path must be absolute
• sqlitePath: A path to where the server should store its SQlite databases
  • Works in conjunction with NODE_ENV=sqlite
  • The path must be absolute
• logFilePath: A path to where the server should store its logfiles. The path must be absolute
• container: An addict-ioc InvocationContainer, where the server should register its dependencies at
• minimalSetup: If set to true, the server will only perform ioc registrations, but nothing else
  • Use this, if you want to launch the AtlasEngine AdminDomain Server manually
  • Defaults to false
• enableHttp: If set to true, all HTTP endpoints the AtlasEngine AdminDomain Server uses will be loaded
  • Use false to prevent the AtlasEngine AdminDomain Server from providing HTTP endpoints
  • Defaults to true
• useHttpRootRoutes: If set to true, the routes / and /security/authority will be set by the AtlasEngine AdminDomain Server
  • Set to false if you want to use these routes for other purposes
  • Defaults to true

Example:

import {InvocationContainer} from 'addict-ioc';
import * as AtlasEngine from '@atlas-engine/admin_domain.application.minimal';

const myInvocationContainer = new InvocationContainer();

await AtlasEngine.launch({
  workDir: `/home/myfancyusername/somedirectory`,
  sqlitePath: `/var/lib/somepath`,
  logFilePath: `var/log/somepath`,
  container: myInvocationContainer,
  minimalSetup: true,
  enableHttp: false,
  useHttpRootRoutes: false,
});

Starting the AtlasEngine AdminDomain Server on system boot

We provide scripts that let you start the AtlasEngine AdminDomain Server automatically as a service.

Currently supported platforms are macOS and windows.

macOS

There are two scripts:

1. start_server_after_system_boot.sh - Causes the AtlasEngine AdminDomain Server to be started automatically as a service
2. do_not_start_server_after_system_boot.sh - Prevents the AtlasEngine AdminDomain Server from being started automatically

If you installed Node.js as a standalone application, you can find the scripts at:

/usr/local/lib/node_modules/@atlas-engine/admin_domain.application.minimal/scripts/autostart

If you installed Node.js via nvm, you can find the scripts at:

/Users/{{YOUR_USERNAME}}/.nvm/versions/node/{{YOUR_NODE_VERSION}}/lib/node_modules/@atlas-engine/admin_domain.application.minimal/scripts/autostart

Usage:

bash autostart/start_server_after_system_boot.sh

The scripts use pm2 to setup the AtlasEngine as an automatically started service.

Note: Currently the do_not_start_server_after_system_boot.sh-script doesn't work under macOS due to a bug in a third party package. As soon as the bug is fixed, we will update the script and release a fix.

Windows

We also provide .bat scripts to setup the server as a global service on windows.

These scripts are located at:

C:\Users\{{YOUR_USERNAME}}\AppData\Roaming\npm\node_modules\@atlas-engine\admin_domain.application.minimal\scripts\autostart

Make sure you run these scripts as Administrator.

During execution of the start_server_after_system_boot.bat script, you will be asked several questions.

Please use the default values on every question.

1. Typing Y and pressing the Enter-key for yes/no questions
2. Just pressing the Enter-key on all other questions.

Application Files

The application files are stored in:

Platform	Folder Path
Macintosch	/Users/<Username>/Library/Application Support/AtlasEngineAdminDomain-Minimal
Linux	/home/<Username>/.config/AtlasEngineAdminDomain-Minimal
Windows	c:\Users\<Username>\AppData\Roaming\AtlasEngineAdminDomain-Minimal

Contained in the application files are the following folders:

Path	Description
databases/	SQLite database files
logs/	Logfiles
metrics/	Recorded metrics

Authors

1. Christian Werner
2. René Föhring