Customization in Container Environment

Last modified 27 Jun 2025 10:39 +02:00
Table of Contents

MidPoint images are prepared to be flexible in usage. You should be able to apply all of the common settings without needing to rebuild the image.

The available options are covered in the /opt/midpoint/bin/midpoint.sh file.

There are two ways in which the file can be used:

  • Environment initialization which covers the common needs related to the initialization of the environment (first run).

  • MP_SET_ environment variable which enables you to customize the image for midPoint runtime.

The midpoint.sh bash script also defines TRAPs.
Without this definition, the TERM or KILL signals would not be passed to the midPoint application in case the container is shut down. If that happened, the application would not have enough time to end operations properly.
From user perspective, the termination of the container does not need to have a 10s timeout before the environment force-kills the container because it only takes a few seconds.

Environment Initialization Variables

This section describes handling of the available files during the initialization of the environment.

The specific behavior is controlled by the environment variables that are described below. These are convenient when you do not have a persistent storage (volume) for the home directory but still want to control initialization of the environment.

To apply the configuration, define the environment variables listed below, and run midpoint.sh init-native.

  • MP_CHECK
    Defines a touch file (can be empty) whose existence is checked during midPoint start. If the file exists, it prevents the application start. If the file is missing, the start continues as usual.

    This is used mainly in advanced scenarios where there is a need to force midPoint to wait until an external condition is met. In the most common use cases, this option will not be useful.

    example
    MP_CHECK=/opt/midpoint/var/init_in_progress

  • MP_INIT_CFG
    Defines the directory to which the config.xml file is copied.

    1. Open the sample config-native.xml which contains the necessary configuration for the native repository.

    2. Update the configuration as needed and save the file as config.xml.

    3. Set the MP_INIT_CFG property to the directory to which you want the file copied during initialization.

    If you do not provide a native repository configuration, a default generic repository config.xml file will be used instead.
    For example, the following sets the target directory as /opt/midpoint/var (the file will be located as follows: /opt/midpoint/var/config.xml)

    MP_INIT_CFG=/opt/midpoint/var

  • MP_DB_PW
    Defines the path to which the generated database password file should be saved. The password for the database access has to be the same on the client and server side.

    You need to generate the password before the DB container is started. As the preferred repository initialization is a push operation (the object is created remotely in a DB that is already running), this cannot be done in one step. Therefore, generating the password for the database means there will be two phases in the container initialization. One for the DB password generation, and another one for the repository initialization.

    example - the generated password will be saved to /opt/db-pw/dbpassword
    MP_DB_PW=/opt/db-pw/dbpassword

  • MP_PW
    Defines the path to which a new generated keystore password is saved as a file. By default, the "changeit" password is used for the keystore. As the default is not secure, it is recommended to have a new password generated instead of using the default:

    1. In the MP_PW variable, define the path to which you want the password generated as a file:
      MP_PW=<path_to_password>

    2. Tell midPoint that you want to use the newly generated password as the keystore password:
      MP_PW_midpoint_keystore_keystorePassword_FILE=<path_to_password>

      example of the value - the generated password will be saved to /opt/midpoint/var/keystorepw
      MP_PW=/opt/midpoint/var/keystorepw

Runtime Environment Variables

This section describes environment variables that you can use for midPoint runtime, i.e. after the environment has been initialized.

  • MP_MP_ENTRY_POINT
    The entry point can be used to copy a file before the system starts. It is mostly used when deploying midPoint in containers, such as in Docker.

  • MP_MEM_MAX
    An alias for the JAVA_OPTS variable -Xmx[0-9] that defines the maximum heap size. It is useful especially if you want to use the key=value syntax, as opposed to more complex sets of values in one variable.

  • MP_MEM_INIT
    An alias for the JAVA_OPTS variable -Xms[0-9] that defines the initial heap size. It is useful especially if you want to use the key=value syntax, as opposed to more complex sets of values in one variable.

  • MP_SET_
    To pass environmental variables to Java more easily, there is a "mapping" for variables starting with MP_SET_. This results in -D parameters in the JAVA_OPTS variable which is already passed to Java. This is beneficial mostly for midPoint run in a container where if you want to pass an additional argument, you need to list all of the already used arguments. With this mapping, it is easier to maintain or even generate the configuration for the container instance.

    In processing, the MP_SET_ prefix is removed, and in the remaining part, "_" (underscores) are replaced with "." (dots). There is an exception, _FILE, which is handled. The -D prefix is added and the final result is then added to the JAVA_OPTS variable which is used for starting midPoint.

MP_SET_ Example

This shows how you can use the MP_SET_ environmental variable in the following scenarios:

Config.xml

Below is a snippet from a sample config.xml file that contains repository configuration.

<?xml version="1.0"?>
<configuration>
    <midpoint>
        <repository>
            <jdbcUrl>jdbc:postgresql://localhost:5432/midpoint</jdbcUrl>
            <jdbcUsername>midpoint</jdbcUsername>
        </repository>
    </midpoint>
</configuration>

To set/overwrite these values, the MP_SET_ environmental variable should be used as follows:

The MP_SET_ environment variable in the Docker Compose syntax
service:
  <service_name>:
    environment:
     - MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://localhost:5432/midpoint
     - MP_SET_midpoint_repository_jdbcUsername=midpoint
The MP_SET_ environment variable in the Kubernetes syntax
spec:
  containers:
    - name: <container_name>
      env:
        - name: MP_SET_midpoint_repository_jdbcUrl
          value: 'jdbc:postgresql://localhost:5432/midpoint'
        - name: MP_SET_midpoint_repository_jdbcUsername
          value: 'midpoint'
The MP_SET_ environment variable in the Docker syntax
docker run -e MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://localhost:5432/midpoint -e MP_SET_midpoint_repository_jdbcUsername=midpoint ...

Embedded Tomcat

You can use the MP_SET_ environmental variable to change the settings of an embedded Tomcat.

Subset of server properties (application.yml)
server:
  port: 8080 # Server HTTP port.

As an example, we can change the port from 8080 to 8081:

MP_SET_server_port=8081

Entry Point

The MP_ENTRY_POINT variable defines the folder in the container’s filesystem which is handled as a read only source mainly for post-initial-objects. The content of the referenced folder is copied to the midPoint structure (/opt/midpoint/var) before starting the midPoint instance, while keeping the same sub-folder structure. During the processing of MP_ENTRY_POINT, a check is performed for the presence of:

  • post-initial-object.done file (a processed post-initial-object is renamed with the suffix .done)

  • *.done files

If such a file exists, i.e. post-initial-object.done or another *.done file, it is skipped so that any future changes on the copied version are kept without overwriting. This means that only new files are copied. This way the post-initial-objects can be re-used several times with the same behavior.

If you are not going to use the MP_ENTRY_POINT feature, you can remove the following configuration lines:

- MP_ENTRY_POINT=/opt/midpoint-dirs-docker-entrypoint
- ./midpoint_server/container_files/mp-home:/opt/midpoint-dirs-docker-entrypoint/:ro

If you do not remove them, the ./midpoint_server/container_files/mp-home directory has to exist. Otherwise, Docker Compose will create it. As the container runs under the root user, the newly created directory will have the permissions set to the root user (UID, GID). To prevent this, make sure the directory structure is prepared in advance.

In theory, you can mount the entry point directly to the midpoint’s structure. However, this may result in one of the following unexpected outcomes:

  • The mount point will be in the "writable" mode.
    In that case, the file will be suffixed with ._done, and it will be ignored in subsequent runs.

  • The mount point will be in the read-only mode.
    MidPoint will fail to start and it will not be possible to rename the file, which is handled as a critical error.

Entry Point Example

In the example below, the following logic is applied:

  • post-initial-objects: The file exists and so nothing changes.

  • user.xml: The user.xml.done file exists in the destination and so nothing changes.

  • role.xml: The file does not exist and so it will be copied to /opt/midpoint/var/post-initial-objects/role.xml.

example of the behavior : MP_ENTRY_POINT=/opt/entry-point
/opt/entry-point
- post-initial-objects
  + user.xml
  - role.xml

/opt/midpoint/var
+ post-initial-objects
  - user.xml.done

Volumes

Until you attach a volume, all changes are kept only in the container which may be discarded. The image is ready to attach the volume to midPoint home - /opt/midpoint/var. By attaching the external store (volume), you will keep the data in the midPoint home directory outside of the container. This makes it safe to remove the container and create a new one by attaching the volume (changing the image version - e.g. new support branch build).

Volumes are handled in the container similarly to mount points. There may be multiple volumes mapped in a cascade.

midPoint structure
/opt/midpoint/var
+ connid-connectors
+ export
+ icf-connectors
| - connector-ssh-1.0.jar
+ idm-legacy
+ import
+ lib
| + jython-standalone-2.7.2.jar
| - ojdbc11.jar
+ log
| + midpoint.out
| - midpoint.log
+ post-initial-objects
+ schema
+ tmp
+ trace
- work
Local filesystem structure
/tmp/workdir
+ connectors
| - connector-ssh-1.0.jar
- docker-compose.yml

To attach the connector subdirectory to a container, use the following definition:

Binding directory from external filesystem to container (Docker syntax)
- ./connectors:/opt/midpoint/var/connid-connectors

You can also bind the file directly:

Binding specific file from external filesystem to container (Docker syntax)
- ./connectors/connector-ssh-1.0.jar:/opt/midpoint/var/connid-connectors/connector-ssh-1.0.jar

Once you use the volume / mount point, the original content will be hidden. Depending on the runtime engine, the original content may be copied into the volume before or during startup. However, once the mount is in place, the original data becomes inaccessible from within the running environment.
Was this page helpful?
YES NO
Thanks for your feedback