README
Process Engine Runtime
This is a stand-alone Server of the ProcessEngine, that can be installed and started globally.
What are the goals of this project
The goal is to provide a ready-to-use environment for utilizing the ProcessEngine.
Table of contents
- Requirements
- Setup
- Starting the ProcessEngineRuntime
- Embedding the ProcessEngineRuntime into another application
- Starting the ProcessEngineRuntime on system boot
- Application Files
- Authors
Requirements
- Node >=
10.15.0
- Python 2.7.x
Setup
Using npm
Install the runtime as a global npm package:
npm install -g @process-engine/process_engine_runtime
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: [processengine:runtime: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 ProcessEngineRuntime
You can start the application with the following command:
process-engine
When started, the ProcessEngine is available at
http://localhost:8000
.
Note: If you're on Windows and the command process-engine
can not be
found, please make sure your PATH
is set correctly.
Global routes
The ProcessEngine exposes a number of global HTTP routes, which you can use to get general information about the application.
These routes include:
http://localhost:8000/
- Base route to get basic details about the ProcessEnginehttp://localhost:8000/process_engine
- Same as abovehttp://localhost:8000/security/authority
- Returns the address of the authority the ProcessEngine uses to perform claim checkshttp://localhost:8000/process_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 ProcessEngine into another web application.
Usually, you'd want to use routes like http://localhost:8000/
for your own
purposes and not have it expose information about any embedded service
(which is what the ProcessEngine would be in this instance).
BPMN Studio uses these global routes to identify remote ProcessEngines to connect to.
The route http://localhost:8000/process_engine
ensures that the studio can do so, even if
http://localhost:8000/
is reserved by your application.
In other words: These routes allow you to access an embedded ProcessEngine through BPMN Studio.
Note:
See the Embedding instructions section
on how to prevent the ProcessEngine from using /
and /security/authority
.
Switching the database
By default, the ProcessEngine 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 process-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 runtime 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 folderNODE_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 runtime
and the environment you wish to use is named production
.
Your configs must then be located in the following path:
- macOS:
/Users/{{YOUR_USERNAME}}/runtime/production
- Linux:
/home/{{YOUR_USERNAME}}/runtime/production
- Windows:
C:\Users\{{YOUR_USERNAME}}\runtime\production
You would need to provide the following environment parameters to access this config:
NODE_ENV
:production
CONFIG_PATH
:- macOS:
/Users/{{YOUR_USERNAME}}/runtime
- Linux:
/home/{{YOUR_USERNAME}}/runtime
- Windows:
C:\Users\{{YOUR_USERNAME}}\runtime
- macOS:
The full start command will then look like this:
- macOS:
CONFIG_PATH=/Users/{{YOUR_USERNAME}}/runtime NODE_ENV=production process-engine
- Linux:
CONFIG_PATH=/home/{{YOUR_USERNAME}}/runtime NODE_ENV=production process-engine
- Windows:
CONFIG_PATH=C:\Users\{{YOUR_USERNAME}}\runtime NODE_ENV=production process-engine
Embedding the ProcessEngineRuntime into another application
The ProcessEngineRuntime is published at npm under the name @process-engine/process_engine_runtime
.
You can add it to your package.json like any other npm package.
To start the runtime, you need to run this command once from inside your application:
import * as ProcessEngine from '@process-engine/process_engine_runtime';
await ProcessEngine.startRuntime(args);
Parameters
The startRuntime
function takes an object with the following optional parameters:
workDir
: A path to where the runtime will store its working data (i.e. 'workspace'). The path must be absolutesqlitePath
: A path to where the runtime should store its SQlite databases- Works in conjunction with
NODE_ENV=sqlite
- The path must be absolute
- Works in conjunction with
logFilePath
: A path to where the runtime should store its logfiles. The path must be absolutecontainer
: Anaddict-ioc
InvocationContainer, where the runtime should register its dependencies atminimalSetup
: If set to true, the runtime will only perform ioc registrations, but nothing else- Use this, if you want to launch the ProcessEngineRuntime manually
- Defaults to
false
enableHttp
: If set to true, all HTTP endpoints the ProcessEngineRuntime uses will be loaded- Use
false
to prevent the ProcessEngineRuntime from providing HTTP endpoints - Defaults to
true
- Use
useHttpRootRoutes
: If set totrue
, the routes/
and/security/authority
will be set by the ProcessEngineRuntime- Set to
false
if you want to use these routes for other purposes - Defaults to
true
- Set to
Example:
import {InvocationContainer} from 'addict-ioc';
import * as ProcessEngine from '@process-engine/process_engine_runtime';
const myInvocationContainer = new InvocationContainer();
await ProcessEngine.startRuntime({
workDir: `/home/myfancyusername/somedirectory`,
sqlitePath: `/var/lib/somepath`,
logFilePath: `var/log/somepath`,
container: myInvocationContainer,
minimalSetup: true,
enableHttp: false,
useHttpRootRoutes: false,
});
Starting the ProcessEngineRuntime on system boot
We provide scripts that let you start the ProcessEngineRuntime automatically as a service.
Currently supported platforms are macOS
and windows
.
macOS
There are two scripts:
start_runtime_after_system_boot.sh
- Causes the ProcessEngineRuntime to be started automatically as a servicedo_not_start_runtime_after_system_boot.sh
- Prevents the ProcessEngineRuntime from being started automatically
If you installed Node.js as a standalone application, you can find the scripts at:
/usr/local/lib/node_modules/@process-engine/process_engine_runtime/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/@process-engine/process_engine_runtime/scripts/autostart
Usage:
bash autostart/start_runtime_after_system_boot.sh
The scripts use pm2 to setup the ProcessEngine as an automatically started service.
Note: Currently the do_not_start_runtime_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 Runtime as a global service on windows.
These scripts are located at:
C:\Users\{{YOUR_USERNAME}}\AppData\Roaming\npm\node_modules\@process-engine\process_engine_runtime\scripts\autostart
Make sure you run these scripts as Administrator.
During execution of the start_runtime_after_system_boot.bat
script, you will be asked several questions.
Please use the default values on every question.
- Typing
Y
and pressing theEnter
-key foryes/no
questions - 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/process_engine_runtime |
Linux | /home/<Username>/.config/process_engine_runtime |
Windows | c:\Users\<Username>\AppData\Roaming\process_engine_runtime |
Contained in the application files are the following folders:
Path | Description |
---|---|
databases/ |
SQLite database files |
logs/ |
Logfiles |
metrics/ |
Recorded metrics |