Installing an xUML Service Image
You can create a dedicated Docker image for single xUML services. To run an instance of the service, create a Docker container from such an image.
This guide describes the steps to perform to do this using docker-compose.
The Installation Process
Step 1: Preparations
Load the xUML Service Docker image with
docker image load -i xuml-service-base-<version>.tar.gz
Step 2: Configure the Installation Settings
Create a folder to contain the xUML Service Docker configuration.
Please note that the docker-compose project is named after this folder. Also, the created Docker containers will get this folder name as a prefix.
Collect the following files to this folder:
the Dockerfile that comes with the xUML Service Docker image
for every service a valid xUML license
the xUML service repository of the service you want to deploy
Create a file docker-compose.yml to the previously created folder. This file should have the following content:
CODEversion: "3.3" services: <your container name>: build: context: . args: REPOSITORY_FILE: <name of your xUML service repository file> XUML_IMAGE: <name of the previously deployed xUML image (see step 1)> image: <your image name>:<your version> hostname: <your machine name> ports: - "<your external service control port>:<your Docker service control port>" - "<your external service port>:<your Docker service port>"
Here, you can change the following settings:
Line | Setting | Description | Allowed Values / Example |
---|---|---|---|
3 | Specify a container name prefix. This name will be appended with a consecutive number. The final name of your container will be:
|
| |
7 |
| Specify the name of the xUML service repository file that should be deployed to the Docker container. |
|
8 |
| Specify the name of the Docker image you have loaded in step 1. |
|
9 |
| Specify the name and version of the dedicated service image to be created from your settings. |
|
10 |
| This hostname must match the machine name the xUML license is bound to. |
|
12/13 |
| Map xUML service Docker container ports to the ports of the host. |
|
Step 3: Build the Service Image
Build the dedicated xUML service image with
docker-compose build
Step 4: Start the Container
Start the container by running the following command:
Docker-compose up
To run the container in the background, use:
Docker-compose up -d
You can stop the container using
docker-compose stop
Service Settings
xUML services can have settings that have been defined with the Builder. These settings are part of the service repository. They may have been set to default values on compile or may have been defined as to be provided by setting variables. Additionally, a service repository that has been exported from a Bridge may contain changed service settings.
When running an xUML service in an xUML service Docker container, you have the possibility to set these settings via environment variables of the container. To do this, add an environment section to the docker-compose file.
environment:
- <setting name>=<setting value>
In this section you can assign values to settings. The name of the setting must be looked up in the service repository.
Unpack the service repository.
Open file substitutions.xml.
Lookup the setting you want to use in section Variables, e.g.
global_SomeIntialValues::Setting for a4
Use the name provided by attribute friendlyId in your docker-compose file, e.g.
G_SOMEINTIALVALUES_SETTING_FOR_A4
and addXUMLT_S_
as a prefix, e.g.XUMLT_S_
G_SOMEINTIALVALUES_SETTING_FOR_A4
Provide a settings value, e.g.
XUMLT_S_
G_SOMEINTIALVALUES_SETTING_FOR_A4=77
Having changed only environment variables in your docker-compose file for an existing image, you do not need to rebuild the image. Just start the container, and the new values will be applied.
The Dockerfile Explained
The xUML service image comes with a Dockerfile that contains the necessary commands to combine the license and the repository to the dedicated xUML service image.
ARG REPOSITORY_FILE
ARG XUML_IMAGE
FROM $XUML_IMAGE
ARG REPOSITORY_FILE
COPY --chown=bridge:bridge license.xml $INSTANCES_HOME/license.xml
#COPY --chown=bridge:bridge logging.json $INSTANCES_HOME/logging.json
ADD $REPOSITORY_FILE /resources/repository.rep
ENV XUML_EXCLUDE_FILES="<path to a file that should be kept>,<another path>"
Line | Variable/Command | Description |
---|---|---|
1 |
| Defines the variable containing the name of the xUML service repository. |
2 |
| Defines the variable containing the name of the base image. |
6 |
| Makes the variable visible to the service image. |
8 |
| Copies the license file into the dedicated service image and applies the necessary user permissions. |
9 |
| Copies the logging setup file to the dedicated service image and applies the necessary user permissions. This line is commented out. |
11 |
| Copies the repository file to the dedicated service image. |
12 |
| Gives the xUML Runtime Tool a list of files that should be kept on deployment. |
Service Startup
Service startup is already integrated to the base image. Nevertheless, you can overwrite the startup command. To do this, add an own command (CMD
) to the Dockerfile, like e.g.
CMD /opt/xuml-tool/xuml-tool run "$REPOSITORY" --service-directory-name <name of the directory> --server-config "$SRV_CONFIG" --existing overwrite)
Using this command, you can deploy (and run) the service to a service directory other than service
(which is the default).
For more details on the options of the xUML tool, refer to xUML Runtime Tool.
Related Documentation: