6. Configure the Engine (Windows)

Now, let’s configure the Axon Ivy Engine with a license and a system database.

First, you have to provide a valid Axon Ivy Engine license. Please refer to Licensing your Engine.

If you do not have a license at this time, skip this section and continue with the next section. Your Axon Ivy Engine will run in Demo Mode.

Besides the license, you need

  • to have a supported SQL database management system server up and running

  • a database user who has the rights to create new databases and execute data definition language (DDL), as well as data manipulation language (DML) statements. The configuration and creation of the system database differ depending on the database system you use. In the following chapters, we will use a PostgreSQL database server.

Important

We support that a DBA creates the database before you start the engine configuration. However, we do not support the external creation or migration of the database structure.

We require DDL permissions during installation and migrations. In normal operations, the database user provided to the engine needs DML permissions only.

There are multiple ways to configure the engine:

  • Using the Engine Cockpit Setup Wizard or Migration Wizard

    This is the most convenient way to configure the engine if this is a one-of-a-kind installation. Please refer to Setup Wizard or Migration Wizard for details.

  • Manually

    See below.

  • Scripted

    If you have several environments and want to set them up in a standardized way, your best option is to automate the manual steps using scripts. We do not provide a script template because there are too many ways to supply licenses, database user credentials, and other data.

6.1. Manual Setup

Shutdown the Axon Ivy Engine first by stopping it. Use ControlCenter.exe or ControlCenterC.exe.

Alternatively, you can use one of the engine executables with command line parameters as detailed in Engine Launchers. These are well-suited for scripting.

  • to stop an engine running as a console process, execute

AxonIvyEngine stop

If you started the engine already as a service, you can also stop it in the services.msc console.

Install the license: Copy the license file (*.lic) into the configuration folder

copy licence.lic <engineroot>\configuration\

To configure the system database, use the:code:config-db command of the EngineConfigCli tool. Replace yourdatabaseserver with the hostname of the server running your DBMS system. Replace dbuser and password with the credentials of a technical database user with the permissions to create a new database and its structures (i.e., DDL permissions) on the database server.

Now, let’s configure the database connection and create the system database:

cd <engineroot>\bin\
EngineConfigCli config-db org.postgresql.Driver jdbc:postgresql://<yourdatabaseserver>:5432/AxonIvySystemDatabase <dbuser> "<password>"
EngineConfigCli create-db

Replace <yourdatabaseserver> with the DNS name of the database server, <dbuser> with the username and <password> with the password of the technical user.

Note

Administrators manage the Axon Ivy Engine. For example, they add or remove users, assign users to roles, enable, disable and deploy applications, etc. You need at least one administrator to manage the Axon Ivy Engine. In case of license problems, the Axon Ivy Engine sends mail notifications to the administrators.

Note

The Axon Ivy Engine internal web server provides connectors for the following protocols:

  • The HTTP Protocol is used by web browsers to communicate with a web server. This protocol is not secure since the communication is not encrypted. Axon Ivy Engine uses port 8080 for HTTP by default.

  • HTTPS is like HTTP, but secure. It uses TLS to encrypt all communication between the web browser and server. Axon Ivy Engine uses port 8443 for HTTPS by default.

Have a look at the ivy.yaml to see how you can adjust parts of the web server and its connectors to your needs.

Now, start the Axon Ivy Engine again.

AxonIvyEngine start

Note

If you have changed the HTTP Settings, the HTTP port of the Axon Ivy Engine may have changed!

Open a web browser and navigate to http://<yourservername>:<yourportnumber>/. As you see, the header with the demo mode message is gone. You now have a production-ready Axon Ivy Engine.

6.1.1. Register the Axon Ivy Engine as a Windows Service

In Windows, you can register your Axon Ivy Engine as a service to execute it in the background. You can do this either graphically by using the Control Center, or in a scriptable way using the command line. Windows provides the service configuration utility sc.exe for this purpose.

AxonIvyEngineService -register [windowsServiceName] [username] [password]

replace [windowsServiceName] with the name you want to use for the service, e.g. ivy_prod. The user specified by [username] and [password] is used to run the service.

Refer to Engine Service for more details on running Axon Ivy as a service.

Hint

You can add dependencies to this service for instance to wait for a DBMS or an external OpenSearch to start before Windows starts the Axon Ivy Engine. Please consult the Windows documentation for further details.