Create a New Database Automatically

This chapter explains how to create a database for ADOGRC. You can create the database automatically using 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 your OCI registry.

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

• The license file you received from your ADOGRC consultant.

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

note

Note for Kubernetes users: This procedure has proven itself in practice and is used in a similar form by the BOC Group when operating ADOGRC 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 command-line parameters).

OCI Registry Credentials

ADOGRC container images and Helm charts are provided through the BOC OCI Registry. You receive the credentials required to access the BOC OCI Registry from BOC Support:

• Registry URL: The BOC OCI Registry URL

• Access Identifier: Access identifier for the repository containing the ADOGRC container images and Helm charts

• Access Token: Authentication token for accessing the ADOGRC container images and Helm charts

Use these credentials to retrieve the required ADOGRC container images and Helm charts from the BOC OCI Registry and make them available in your OCI registry.

caution

The BOC OCI Registry is intended as the source for obtaining ADOGRC container images and Helm charts and is subject to download limits. BOC Group therefore strongly recommends using your own OCI registry, for example by using a pull-through caching registry or a local mirror registry.

Unless stated otherwise, all procedures in this guide assume that the required ADOGRC container images and Helm charts are available in your OCI registry.

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 subdirectories for variables and commands. If you choose a different directory, adapt the directory paths used in the Docker 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.

note

To keep our examples simple, we have decided to use the folder /opt/data/ as the working folder. This folder is usually available and allows us to use absolute paths as opposed to relative paths in a users home folder. You can, of course, use any other folder, just make sure that, when you use paths used by processes in the container, you define them from the point of view of the container and not the host.

note

The logs created during the upgrade are written with a user in the container who doesn't exist on the host system. It is therefore necessary to allow write permissions to all on the logs folder. You can set these with the command chmod o+w /opt/data/logs.

Log in to the OCI Registry

Log in to your OCI registry 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 <container-registry-url>. Follow the prompts to enter the credentials required by your OCI registry.

caution

By default, this command stores the credentials in the Docker configuration file (default: ~/.docker/config.json). If you are currently deploying ADOGRC, you can use this file when you log in to the container registry with Helm and creating the ImagePullSecret, but make sure to safely delete this file afterwards.

note

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

After preparing the data directory, license file, and optional custom library, execute the following command on the Linux machine or in your WSL environment to create the database.

docker run -it --rm \
  --entrypoint /aserver/amain \
  -v /opt/data/logs:/aserver/logs \
  -v /opt/data:/opt/data \
  <fully-qualified-image-name> \
  --mode install \
  -db "<database-server>:<database-name>" \
  -dt "<SQLServer|PostgreSQL>" \
  -dbadmin "<database-admin-name>" \
  -dbadminpw "<database-admin-password>" \
  -lic "/opt/data/license/license.xxl" \
  -lib "/aserver/data/default.axl" \
  -prlang "<language-code>"

The command starts a short-lived Docker container using the ADOGRC application server image. The container executes amain to create the database and is removed automatically after the operation completes.

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

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 command fails with an SSL or certificate validation error, review the SQL Server encryption settings and adjust these parameters accordingly.

note

ADOGRC 15.0 does not support Windows Authentication for Microsoft SQL Server databases. Use SQL Server Authentication instead.

The most important parts of the command are:

• --entrypoint /aserver/amain: Executes the database management tool directly instead of starting the application server.

• -v /opt/data/logs:/aserver/logs: Stores the log files generated during database creation in the /opt/data/logs directory on the host system.

• -v /opt/data:/opt/data: Makes the data directory, including the license file and optional custom library, available to amain inside the container.

• <fully-qualified-image-name>: Specifies the fully qualified name of the application server image in your OCI registry.

The database-related command parameters are:

• -db "<database-server>:<database-name>": Specifies the database server and database name in the format <database-server>:<database-name>.

• -dt "<SQLServer|PostgreSQL>": Specifies the database type. Supported values are PostgreSQL or SQLServer.

• -dbadmin "<database-admin-name>": Specifies the username of a database administrator with permission to create databases.

• -dbadminpw "<database-admin-password>": Specifies the password of the database administrator.

The installation-specific command parameters are:

• -lic "/opt/data/license/license.xxl": Specifies the path and file name of your ADOGRC license file.

• -lib "/aserver/data/default.axl": Specifies the application library to import. If you want to use the ADOGRC Standard Application Library, keep the default value /aserver/data/default.axl. To import a custom application library, replace it with the path and file name of your library file.

• -prlang "<language-code>": Specifies 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.

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 ADOGRC.