Linux (with console tools only)¶
In this section, you will learn how to install and configure an Axon.ivy Engine on a Linux server only using the console. On the Linux machine no windowing system has to be installed. However, to test your configuration a client machine with a web browser is needed.
Prepare your Machine¶
Before starting with the installation of Axon.ivy Engine prepare your Linux machine with the necessary tools and software needed for the installation (wget, unzip, Java 11 runtime). Most distribution may have pre-installed these tools but especially certain Docker images may have not. On Debian (e.g. Ubuntu, etc.) based system use:
apt update apt install sudo wget unzip openjdk-11-jre-headless
Install the Engine¶
We suggest that you install the Axon.ivy Engine into a new folder called
/opt/ivy/engine. Create the directory and change the owner to your current
cd /opt sudo mkdir ivy sudo chown myuser:myuser ivy
Replace myuser with the name of your current user.
Instead of using your current user we suggest that on a productive system
you use a special user called ivy. First, create a new user and group
called ivy. Then, change the owner of the folder
ivy to the user
ivy. After that, login as user ivy and work with the new user.
sudo mkdir ivy adduser ivy ... sudo chown ivy:ivy ivy ls -al ... drwxr-xr-x 3 ivy ivy 4096 Sep 15 11:26 ivy ... login ivy ...
Download the latest engine
cd ivy mkdir engine cd engine wget https://developer.axonivy.com/permalink/8.0/axonivy-engine.zip -O engine.zip
To install Axon.ivy Engine simply unzip the downloaded file
AxonIvyEngine*.zip into a new
unzip engine.zip -d latest rm engine.zip cd latest
The most important folders of the Axon.ivy Engine are:
binfolder which contains all the executables.
configurationfolder which contains the configuration files.
deployfolder which is used to deploy Axon.ivy projects.
Start the Engine¶
Start the Axon.ivy Engine by navigation to the bin folder and executing the
cd bin ./AxonIvyEngine
This will start the Axon.ivy Engine as a user process. On the last lines of the output a URL is displayed
[100%] Service ProcessModelVersion Portal/AxonIvyExpress$1 started [0ms] Go to http://yourservername:8080/ivy to see the info page of Axon.ivy Engine. Axon.ivy Engine is running and ready to serve. [9375ms] Type 'shutdown' and confirm with ENTER to stop the running engine instance
Copy this URL. On your client machine open a web browser and navigate to that URL. This will display the Axon.ivy Engine main page.
Normally, you want to run Axon.ivy Engine as a daemon process and not as a user
process. You can register and manage the Axon.ivy Engine daemon using
Use the Engine¶
The main page of the Axon.ivy Engine looks like this
The Axon.ivy Engine is running in Demo Mode. This is because you did not install a valid license yet nor did you configure a system database. Note, that everything that you do with the Axon.ivy Engine running in Demo Mode is lost when you shut down the engine. However, you can use the engine also in Demo Mode and tryout the pre-installed Portal application by clicking on the Portal Home link. To login use one of the predefined demo users: demo, guest or admin. The passwords of the demo users are equal to the user names (E.g. demo for the demo user). Login as demo user and try to create a TODO task for the guest user using the Axon.ivy Selfservice process:
Configure the TODO task as follows:
Start the workflow by pressing the Start Workflow button. After that, logout, then login again as guest user. On the task list, you now see the new TODO task that you created before. Try to work on the task by clicking on it:
Go ahead and play around with the Selfservice process. Try out different types of tasks.
In Axon.ivy a task is a piece of work (a part of a process) that is assigned to a user or role. A user to whom a task is assigned or who has the role to which a task is assigned can work on the task. When a user works on a task the task disappears from the task list of other users who might also able to work on the task. This means only one user can really work on a task at the same time. In a process, it is possible to define parallel tasks. Therefore, it is possible that two or more users work parallel on different tasks of the same process instance. In Axon.ivy a process instance is called a case.
Configure the Engine¶
Now, let’s configure the Axon.ivy Engine with a license and system database.
To start with that you must first request a valid Axon.ivy Engine license. Either you get a license for your productive system through one of our sales personal or contact our support for time limited tryout licenses. If you do not have a license you can skip this section and continue with the next section.
Moreover, you need to have a supported database server up and running with a database user that has the rights to create new databases. The configuration and creation of the system database differs a little bit depending on the database system you use. We will use a PostgreSQL database server.
Shutdown the Axon.ivy Engine first by typing shutdown and Y:
... Go to http://ivy1:8080/ivy to see the info page of Axon.ivy Engine. Axon.ivy Engine is running and ready to serve. [11596ms] Type 'shutdown' and confirm with ENTER to stop the running engine instance shutdown Should 'Axon.ivy Engine' be stopped? ([Y]es / [N]o): Y Stopping Axon.ivy Engine ... [ 0%] Stopping Server ...
Let’s install the license. You can do this by simple copy the license
file into the
cp ~/license.lic /opt/ivy/engine/latest/configuration
To configure the system database, use the
config-db command of the
EngineConfigCli tool. Replace yourdatabasserver with the name of the
host where your PostgreSQL server is running. Replace dbuser and
password with the credentials of a database user that has the rights to
create a new database on the database server.
./EngineConfigCli config-db org.postgresql.Driver \ jdbc:postgresql://yourdatabaseserver:5432/AxonIvySystemDatabase \ dbuser password
Now, let’s create the system database with the
The system database is used by Axon.ivy Engine to store configurations, users, roles, process instances, tasks and process data.
Next, define an administrator by modifying the ivy.yaml file of the
1 2 3 4 5
# sample ivy.yaml which defines a single administrative account: Administrators: admin: Password: 1234 Email: firstname.lastname@example.org
Administrators can administrate the Axon.ivy Engine. For example, they can add or remove users, assign user to roles, enable or disable applications, etc. Therefore, you need at least one administrator so that you can later administrate the Axon.ivy Engine. The Email address of administrators are used to send mail notifications if license problems occur.
Lastly, disable the AJP protocol connector of the Axon.ivy Engine internal web
server in the ivy.webserver.yaml file of the
1 2 3 4
# sample ivy.yaml which disables AJP, as no front-end webserver is in charge: Connector: AJP: Enabled: false
The Axon.ivy Engine internal web server provides connectors for the following protocols:
Protocol used by web browser to communicate with a web server. This protocol is not secure since the communication is not encrypted. Axon.ivy Engine uses port 8080 by default.
Like HTTP but secure. It uses TLS to encrypt the communication between the web browser and server. Axon.ivy Engine uses port 8443 by default.
This protocol is used to communicate with a Microsoft IIS or Apache httpd front-end server. AJP means Apache Jakarta Protocol. Axon.ivy Engine uses port 8009 by default.
Have a look at the ivy.webserver.yaml to see what other parts of the webserver and its connectors can be adjusted for your needs.
Now, start the Axon.ivy Engine again as background process.:
nohup ./AxonIvyEngine &
Note, that the HTTP port of the Axon.ivy Engine may have changed. If you did change the http settings! So open again a web browser and navigate to http://yourservername:yourportnumber/ivy. Note, that the header with the demo mode message is gone. You now have a production ready Axon.ivy Engine.
Deploy an Axon.ivy project to the Engine¶
Let’s deploy an Axon.ivy project to the Axon.ivy Engine. We use demos that are shipped with the Axon.ivy Designer.:
cd /var/lib/axonivy-engine-8/deploy sudo -u ivy wget https://developer.axonivy.com/permalink/lib/dev/demos.zip
Here we deploy a new application by dropping packed (IAR) projects into it. However it is also possible to deploy full applications as ZIP or unpacked projects.
You can monitor the deployment with:
tail -f demos.zip.deploymentLog
As soon as the deployment is finished the zip-file will be postfixed with
.deployed. In case of an error the postfix is
An Axon.ivy Engine can manage multiple applications. Each application has its own user and task management. A user of one application can only work in that application and not in another application. A task of one application will never be visible in another application. Therefore, applications can be used to build multi tenancy or stages (DEV, Q&A, PROD) without to install multiple Axon.ivy Engines.
Refresh the main page of the Axon.ivy Engine. There is now a new application called IvyDemoApp with a section called WorkflowDemos. Under it links are available to start processes.
Congratulations you have installed and configured your first Axon.ivy Engine and also deployed your first Axon.ivy processes.