Create a New Database Automatically

This chapter explains how to create a database for ADONIS. You can create the database automatically using an environment file and a short-lived Docker container spawned from the application server image. This automated procedure runs the BOC Management Tool amain inside the container to provision your database structure, after which the container is automatically stopped and removed.

Prerequisites

Before you can create a BOC Management Office® database, you need to have the following:

• A database server running a supported version of Microsoft SQL Server or PostgreSQL.

• A Linux machine, or Windows Subsystem for Linux (WSL), with Docker Engine (the Docker daemon) set up and network access to the database server and the BOC OCI Registry.

• Login credentials for the database server with permissions to create new databases.

• The license file you received from your ADONIS consultant.

• In case you are not using a standard library, the custom library you received from your ADONIS consultant.

Remarque

Note for Kubernetes users: This procedure has proven itself in practice and is used in a similar form by the BOC Group when operating ADONIS in its own SaaS environment based on Kubernetes. If you do not have or want to use Docker directly in your Kubernetes environment, you can modify the procedure described below accordingly (e.g., by deploying a temporary Kubernetes pod or a Kubernetes job with the same environment variables and parameters).

Preparing a Directory for Data

Create a directory on your administrative machine for files needed during database creation. In this example we will create a directory /opt/data/, and use this directory and sub-directorys for variables and commands. If you choose a different directory, adapt the variables in the environment file and the mapped directorys in the docker run command.

• Place the license.xxl file in /opt/data/license/

• If you are using a custom library, place library.axl in /opt/data/library/

• Create a directory /opt/data/logs/ to keep logs persistent after the temporary container was removed.

Preparing the Environment File

Create an environment file named amain.env on your administrative machine. This file contains all necessary database connection details, as well as the path to the license and library files.

• Create a plain text file with the following configuration and adjust the values according to your environment:

  DBNAME=<my-database-name>
  DBTYPE=<SQLServer|PostgreSQL>
  DBADMIN=<my-database-admin-name>
  DBADMINPW=<my-database-admin-password>
  LICENSE=/opt/data/license/license.xxl
  LIBRARY=/aserver/data/default.axl
  PRIMARYLANG=<primary language>

Here is an explanation of the required variables within the file:

• DBNAME: The database connection identifier. For PostgreSQL and MSSQL deployments, this must be specified in the format hostname:database_name (e.g., db-server:adonisdb).

• DBTYPE: The type of your database management system. Supported values are PostgreSQL or SQLServer.

• DBADMIN: The username of your database administrator possessing sufficient privileges to modify the application database schema.

• DBADMINPW: The password belonging to the specified database administrator user.

• LICENSE: The path and file name of the license file you received from your ADONIS consultant.

• LIBRARY: The ADONIS BPMS Application Library is already part of the container image. The default location is /aserver/data/default.axl, so you do not need to change this variable. If you are using a custom library, change this variable to /opt/data/library/library.axl

• PRIMARYLANG: The language code for the primary language used when creating models and objects. It serves both as default and as fallback language if some text is not available in other languages. Common values include en (English), de (German), fr (French), etc., depending on the library and license.

Important

The paths to the license file and library file, are the paths inside the container, not on the host. In our example, we create a directory /opt/data/ and map this into the container as /opt/data/. By using the same directory names in the container and on the host, we avoid potential issues when mixing up directorys inside and outside the container.

Log in to the BOC OCI Container Registry

To log in to the BOC OCI container registry, you will need the access informations and credentials you received from your ADONIS consultant. Login to the BOC OCI registry is required to access the image for the temporary container used to create the database.

The easiest way to log in is to use the standard docker command docker login <boc-registry>. This will prompt you for an access id ("user name") and an access token ("password").

Attention

This command stores the credentials in the docker config file in clear text (default: ~/.docker/config.json). If you are currently deploying ADONIS, you can use this file when you log in to the BOC OCI registry with Helm and creating the ImagePullSecret but make sure to safely delete this file afterwards.

Remarque

Do not pass credentials directly as command parameters, the bash command history stores a list of recent commands and could therefore inadvertently reveal the credentials.

Executing the Command to Create the Database

Here is an example of the command used to create the database. If you are using different directorys for data, adapt the parameters accordingly.

docker run -it --rm \
  --entrypoint "" \
  --env-file amain.env \
  -v <log file path>:/aserver/logs \
  -v <data directory>:/opt/data \
  <boc-registry> \
  sh -c '/aserver/amain \
    --mode install \
    -db "$DBNAME" \
    -dt "$DBTYPE" \
    -dbadmin "$DBADMIN" \
    -dbadminpw "$DBADMINPW" \
    -lic "$LICENSE" \
    -lib "$LIBRARY" \
    -prlang "$PRIMARYLANG"'

Info

For Microsoft SQL Server, amain uses encrypted database connections by default, matching the default behavior of Microsoft ODBC Driver 18 for SQL Server. If your SQL Server is not configured for encrypted connections, specify --encrypt "optional". If your SQL Server uses an encrypted connection with an untrusted server certificate, you may also need to specify --trustservercertificate "yes". PostgreSQL does not require these parameters.

If the upgrade fails with an SSL or certificate validation error, review the SQL Server encryption settings and adjust these parameters accordingly.

Remarque

ADONIS 19.0 does not support Windows Authentication for Microsoft SQL Server databases. Use SQL Server Authentication instead.

Here is an explanation of the placeholders in the command:

• <log file path>: The directory you created for the log files, in our example /opt/data/logs

• <data directory>: The directory you created for the license and library, in our example /opt/data

• <boc-registry>: The BOC OCI Registry from where Docker downloads the image for the temporary container.

The command will pull the container image from the BOC OCI Registry, start the container and execute the command to create a database. After the command finishes, the container will be stopped and removed automatically.

Important

The BOC Management Tool writes log files to /aserver/logs per default. As this directory is inside the container, it will no longer exist after the container is removed. For this reason we map the directory we created in our example /opt/data/logs on the host over the directory /aserver/logs in the container. This way the logs will be written to the host directory and remain available after the container is automatically removed at the end of the command.

The database is now ready for use. You can remove any temporary files you no longer need.

Default User

During the creation of the database, a user account is created automatically: The user Admin (with the starting password password) is a super user for administrating ADONIS.