Skip to main content
Version: 15.0

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 the BOC 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).

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 BOC OCI Container Registry​

To log in to the BOC OCI container registry, you will need the access information and credentials you received from your ADOGRC 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").

caution

This command stores the credentials in the docker config file in clear text (default: ~/.docker/config.json). If you are currently deploying ADOGRC, 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.

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 \
  <boc-registry> \
  --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.

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

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 the license file you received from your ADOGRC consultant.

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