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.

Note

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.

Launchers

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.

Note

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.

License

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

../../_images/engine-cockpit-setup-licence.png

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.

Note

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:

../../_images/engine-cockpit-setup-admins.png

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:

../../_images/engine-cockpit-setup-webserver.png

The following protocols are supported:

Protocol

Description

HTTP

HTTP protocol

HTTPS

HTTP protocol over secure socket layer (SSL).

AJP

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

Note

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:

../../_images/engine-cockpit-setup-systemdb.png

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)

  • INSERT, SELECT, UPDATE, DELETE data

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.

Note

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)

  • INSERT, SELECT, UPDATE, DELETE data

The best practice configurations are documented in chapter System Database.

Convert a Existing System Database

Warning

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.

Warning

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.