Setup Wizard

The Setup Wizard is a simple user interface for operators to apply the initial configuration that is necessary to turn a demo engine into a productive Axon Ivy Engine instance. This includes among other steps the installation of a license and the creation of a system database.


The changes that you make with the Setup Wizard do not become active unless you restart the engine. However, configurations are constantly written from the wizard to the ivy.yaml file.

Advanced users might prefer to manually craft configurations in ivy.yaml and use the EngineConfigCli to roll out an Axon Ivy Engine into production. Configuration files make the installation process quickly reproducable in various environments such as dev, test and prod.


Start the Engine Launchers using its launcher. If the engine runs in the Demo Mode you see a warning on the info page with a link to the Setup Wizard. E.g. http://myServer:myPort/system/faces/view/engine-cockpit/setup.xhtml

If you are not able to start the Axon Ivy Engine anymore, you can remove the installed license file from the configuration directory. The Axon Ivy Engine should now start up in Demo Mode.


For the usage of this tool, you will need an administrator user account. If you run in Demo Mode the administrator user and password is admin.


In the License step you have to upload a valid license:


Use the Choose license button to open the file browser and select the license file which should be used or simply drop your license file inside the marked field.


It is possible to configure the engine without a valid license, but the engine will always start in the Demo Mode if you do not have a valid license and therefore cannot use your configuration.

System Administrators

On the Administrators step you can configure users that have the right to administer the Axon Ivy Engine:


Defining an email address for the administrators is mandatory. Notifications of critical events, such as license violations, are sent to administrator email addresses.

Web Server Ports

In the Web Server step you enable and configure the web protocols of the Axon Ivy Engine. Furthermore, you can customize the IP port bindings:


The following protocols are supported:




HTTP protocol


HTTP protocol over secure socket layer (SSL).


Apache Jakarta Protocol. This protocol is used to integrate a reverse proxy like IIS or Apache. Deprecated - use HTTP or HTTPS!


In case you disable HTTP port, then the specified port will still be opened by the engine for internal purposes. However, the engine will refuse connections from remote hosts.

System Database

In the System Database step the Axon Ivy Engine, you can configure, create and convert system databases:


First choose the database system and the JDBC driver you want to use. At the moment the Axon Ivy Engine supports the following database systems:

In the second part you need to define you connection settings. These depend on the chosen database system and JDBC driver. Click on the database system links above to find information about how to configure the connection settings. The applied db user needs the following privileges:

  • CREATE DATABASE (to create the system database out of the Engine Configuration)

  • CREATE, ALTER, DROP: Tables, Views, Indexes, Triggers (to update the Axon Ivy Engine)


In a third step, you may configure additional connection properties. When clicking on the Add Property button a dialog will allow you to add properties. See System Database to find information which additional connection properties are available for the database system that you have chosen.

At the top of the page the state of the connection is visible. Use the button Check Connection to try to connect to the system database once you have finished your configuration.

Create New System Database

If the system database does not exist, use the Create Database button to create a new system database. During the creation of a new database the configured connection settings are used. Some additional information may be required. It has to be defined in the creation dialog. See System Database to find what additional information is necessary for the chosen database system.


You can previously create an empty database/schema. In this case the wizard will only create the necessary tables into the given database/schema. If the database/schema doesn’t exist already, the wizard creates it with a best practice configuration. In this case the applied db user needs the following privileges:

  • CREATE, ALTER, DROP: Tables, Views, Indexes, Triggers (to update the Axon Ivy Engine)


The best practice configurations are documented in chapter System Database.

Convert a Existing System Database


We strongly recommend to backup your database before you convert it to a newer version. Be sure that you have enough disk/table space on your database server. Most conversions add new fields to existing database tables which will enlarge the used database space.

If the system database has an older version, use the Migrate Database button to convert it to the latest version.


Depending on the conversion steps and your database system it may be necessary to cut all connections to the system database to avoid problems. If you have problems with the conversion, please disconnect all other database management tools, clients or other tools which have a connection to the system database and try again.