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
- Setup
- Starting the 5Minds Engine
- Starting the 5Minds Engine via Docker
- Configuring the 5Minds Engine
- Global Http Routes
- Embedding the 5Minds Engine into another application
- Register Event Middleware
- Working Directory
- Authors
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
- Creating volumes
docker volume create atlas-engine-db
docker volume create atlas-engine-configuration
- 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 tofalse
. - 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 Enginehttp://localhost:10560/atlas_engine
- Same as abovehttp://localhost:10560/security/authority
- Returns the address of the authority usedhttp://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 istrue
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 absolutesqlite-path
: A path to where the server should store its SQlite databases- Works in conjunction with
NODE_ENV=sqlite
- The path must be absolute
- Works in conjunction with
use-http-root-routes
: If set totrue
, 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
- Set to
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.