@atlas-engine/fullstack_server

A Server application that contains all four domains that make up the AtlasEngine.

Usage no npm install needed!

<script type="module">
  import atlasEngineFullstackServer from 'https://cdn.skypack.dev/@atlas-engine/fullstack_server';
</script>

README

5Minds Engine

This is a stand-alone application for hosting the 5Minds Engine. The application can be installed and started as a global npm application, or as a Docker container.

Table of contents

Requirements

  • Minimum NodeJS Version: >= v14.15.x
  • Recommended NodeJS Version: >= v16.13.x
  • On Windows Systems: The Windows Build Tools
  • A running and accessible authority (i.e. Identity Server or something similar)
    • The engine requires this authority for verifying user identities
    • See the Configuring the Authority section for setup instructions

When using MySQL, PostgreSQL or MS SQL Server, an instance of the respective database has to be running and accessible. Please refer to the Configuration section for more information.

Setup

Using npm

Install the latest version as a global npm application:

npm install -g @atlas-engine/fullstack_server

Note: On Windows systems, be sure to run the command shell as Administrator.

Using docker

A docker image of the 5Minds Engine is available at Dockerhub.

You can use docker pull for downloading an engine image:

docker pull 5minds/engine

To install a specific version, you can append a version suffix:

docker pull 5minds/engine:13.0.7

You can pull the latest version for a specific major release, by using a :majorversion tag. For example, the following command will pull the latest image for Major version 13:

docker pull 5minds/engine:13

Starting the 5Minds Engine

If you installed the 5Minds Engine as a global npm application, you can use the following command to start it:

CONFIG_PATH=/<path_to_configfile>/<filename>.json atlas-engine

Note that CONFIG_PATH will default to the internal sqlite.json config, if not provided.

When started, the 5Minds Engine is available at

http://localhost:10560

Each release channel uses a different default port:

release channel port
stable 10560
beta 10570
alpha 10580
dev 10590
docker 80

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

Starting the 5Minds Engine via Docker

To start the 5Minds Engine via docker, run:

docker run -p 10560:10560 5minds/engine

If you want to use a custom config, use the following command

docker run -p 10560:10560 -d --env CONFIG_PATH=<path-to-config-file-in-docker-container> -v <file-to-mount>:<destination> 5minds/engine

Replace <file-to-mount> with the path to the custom config file. Replace <path-to-config-file-in-docker-container> and <destination> with the path where the custom config file should get mounted to.

Example:

docker run -p 10560:10560 -d --env CONFIG_PATH=/mnt/config/sqlite.json -v ${PWD}/sqlite.json:/mnt/config/sqlite.json 5minds/engine

Default Docker Volumes

By default, the SQLite database and the config file are stored in two separate volumes. Both volumes are automatically created and mounted when the container is started.

Custom Docker Volumes

  1. Creating volumes
docker volume create atlas-engine-db
docker volume create atlas-engine-configuration
  1. Using the created volumes
docker run \
  --mount source=atlas-engine-db,target=/root/.config/AtlasEngineFullstackServer/databases \
  --mount source=atlas-engine-configuration,target=/usr/local/lib/node_modules/@atlas-engine/fullstack_server/configs/ \
  \
  --publish 10560:80 \
  \
  5minds/engine:latest

Configuring the 5Minds Engine

We provide a number of sample configurations, named after the databases we currently support.

These are located in the configs folder and include samples for:

sqlite.json is used as default configuration. The corresponding SQLite database will be placed in a databases directory, of the Working Directory section.

If you want to use a different database, you must provide a CONFIG_PATH parameter, which points to a different configuration. The path to that file can be relative or absolute.

For example, if you wish to use the default config for accessing a Postgres database, use:

CONFIG_PATH=./configs/postgres.json atlas-engine

Configuring the authority

The Engine requires an authority to be present at the configured address. The address can be set through the config file's iam section.

By default, all endpoints require the user to provide a valid jwt auth token. If you want to allow anonymous access (i.e. without login) you can do so, by setting allowAnonymousRootAccess to true.

In this case, a requesting user can use the dummy token ZHVtbXlfdG9rZW4= with each request. This is basically a placeholder that tells the engine "the requesting user is not logged in" and that a request against the authority is not necessary. Use this, if you do not want to use an authority.

Be advised:

  • This token will not be accepted, if allowAnonymousRootAccess is set to false.
  • Dummy tokens provide full access to all endpoints and all engine data, including that of logged in users! Use with caution

Providing custom configurations

If you want to use your own config file, you can use one of the sample configs as a template. To tell the engine to use your custom config file, set CONFIG_PATH to the config file's location.

The path to the config file can be relative or absolute.

Note that the config must be provided as JSON.

Global Http Routes

The 5Minds Engine exposes a number of global HTTP routes, which you can use to get general information about the engine.

These routes include:

  • http://localhost:10560/ - Gets basic details about the 5Minds Engine
  • http://localhost:10560/atlas_engine - Same as above
  • http://localhost:10560/security/authority - Returns the address of the authority used
  • http://localhost:10560/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 5Minds Engine into another web application. Usually, you'd want to use routes like http://localhost:10560/ for your own purposes and not have it expose information about an embedded service (which is what the 5Minds Engine would be in this instance).

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

In other words: These routes allow you to access an embedded 5Minds Engine through 5Minds Studio.

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

Embedding the 5Minds Engine into another application

The 5Minds Engine is available at npm under the name @atlas-engine/fullstack_server. You can add it to your package.json like any other npm package. To start the engine, you need to run this command from inside your application:

import * as Engine from '@atlas-engine/fullstack_server';

await Engine.launch(args);

Embedding Options

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

  • enable-http: If set to true, the engine's API will be exposed through HTTP. Default is true
  • extensions-dir: A path to an extensions directory
    • By default extensions will be loaded from '${HOME}/.atlas/engine/extensions'.
    • The path must be absolute.
  • name: Sets the name of the 5Minds Engine instance.
  • require: A path to an event middleware.
    • An event middleware is a function that gets called every time an 'EngineEvent' is triggered.
    • The path must be absolute.
  • seed-dir: A path to a folder of BPMN files that are imported at startup. The path must be absolute
  • sqlite-path: A path to where the server should store its SQlite databases
    • Works in conjunction with NODE_ENV=sqlite
    • The path must be absolute
  • use-http-root-routes: If set to true, the routes / and /security/authority will be used by the 5Minds Engine to expose basic information about the application
    • Set to false if you want to use these routes for other purposes
    • Defaults to true

Example:

import {Container} from 'inversify';
import * as Engine from '@atlas-engine/fullstack_server';

const myContainer = new Container();

await Engine.launch({
  sqlite-path: `/var/lib/somepath`,
  enable-http: false,
  use-http-root-routes: false,
  name: 'Test-Engine',
  seed-dir: `/home/myfancyusername/somedirectory/bpmns`,
});

Register Event Middleware

An event middleware is a function that gets called every time an EngineEvent is triggered. These middlewares will block the execution of the ProcessInstance that triggered the event, until all middlewares have finished.

To register an event middleware, start by creating a new script based on the following schema:

registerEventMiddleware(async (engineEvent) => {
  console.dir(engineEvent, {depth: null});

  await doStuff(engineEvent);
});

The registerEventMiddleware function is available in the global context. For that reason it is not necessary to import it from the 5Minds Engine package.

To add your middleware to the 5Minds Engine, you must provide the path to the middleware with the --require parameter during startup.

Example: atlas-engine --require <path-to-script>.

Working Directory

The engine uses the following directory for storing its local data:

Platform Folder Path
macOS /Users/<Username>/Library/Application Support/AtlasEngineFullstackServer
Linux /home/<Username>/.config/AtlasEngineFullstackServer
Windows c:\Users\<Username>\AppData\Roaming\AtlasEngineFullstackServer

This currently includes the SQLite database that is used by default.

Authors

  1. Christian Werner
  2. Sebastian Griesa
  3. René Föhring