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 especially 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. Even though, 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 and Axon.ivy Engine into production. Configuration files make the installation process faster re-reproducible in various environments such as dev, test and prod.

Launchers

Start the Axon.ivy Engine 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/ivy/faces/view/system/engine-cockpit/setup.xhtml

If you are not able to start the Axon.ivy Engine anymore, you may 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.

Licence

On the Licence step you have to upload a valid licence:

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

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

Note

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

System Administrators

On the Administrators step you can configure users that have the right to administrate 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 licence violations, are sent to administrator email adresses.

Web Server Ports

On the Web Server step you can configure the enabled web protocols of the Axon.ivy Engine. Furthermore, IP port bindings can be customized:

../../_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 for the communication of the embedded Servlet Engine with external WebServers like IIS or Apache.

Note

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

System Database

On the System Database step the Axon.ivy Engine system database can be configured, created and converted:

../../_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:

On the second part you need to define you connection settings. Those depends 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 can configure additional connection properties. When clicking on the Add Property button a dialog will show, where you can add properties. See System Databases 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.

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, but may some additional information is necessary. It must be defined in the creation dialog. See System Databases 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 an old 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 that has a connection to the system database and try again.