Tutorial

Customization

iManager has the ability to integrate customized compose applications(industry application). In the existing compose applications, the SGS is integrated into the iManager after some customization, and the SGS is created, managed, distributed and monitored through iManager.

If you want to manage your applications through iManager, you need to customize the following:

Compose customization steps

Make mirrors

To container your own application docker, it is recommended to use dockerfile to make your own application into Docker image. The specific method of making mirror can refer to Docker official website documents.
Write docker-compose.yml file

The rules for writing the docker-compose.yml cant be found in Docker official website documents.
Write rule.yml file

Write the rule.yml file using the YAML language. See the “Description of rule documents”。
Integrated into iManager

Get the location of imanager-config by “docker inspect imanager”, as shown in figure:

Then create a new folder under the appSet folder of path(the name of the folder will default to the name of compose application on the interface), and place the docker-compose.yml file and rule.yml written in the above steps under the folder.
Use the customized compose application

After completing the steps 1-4 above, you can see your own custom application in the left menu of the iManager interface under the compose application. You can create, monitor and manage your compose applications.

Description of rule documents

version: #The version of the rule file and its type is String
appSetListPage: #Process the compose application list page
  serviceTemplate: #List page displays the information of template, processing list page IP, port display
    serviceName: #The serviceName is the name of the service corresponding to the address displayed on the list page, which is consistent with the service in the docker-compose.yml file and its type is String.
    urlTemplate: #The url template and its type is String.
    portTemplate: #The template for showing port adnd its type is String.
    cluster: #Is it the cluster? The cluster here refers to the single machine cluster using nginx, the value is true or false.
    clusterInternalPort: #In the case of nginx, specify a port in nginx to display on the list page, and its type is String.
    specifyExposedPort: #Whether the current container exposes the specified port adnd its type is String.
    specifyExposedPortLabelKey: #The external port corresponding to which internal port is currenty exposed and its type is String.
    appSetBaseName: #Docker does not allow to create containers with Chinese names, so iManager specify a base name that meets the requirement for each type of compose application.
createAppSetPage: #Process the compose application creation page
  - type: #The types of elements are described in detail below.
    position: #The location of the element, with a value of basic or advanced, basic indicates the required location, and advanced indicates the location of the advanced option.
    portIndex: #The index of the port element and its type is int.
    serviceName: #The container service name behind the element corresponds to the service neme in the docker-composer.yml file and its type is String.
    placementIndex: #The index of placement in the multi machine rule file, and its type is int.
    display: #Displays the current element with a value of true or false.
    item: #Element entries, as specified below
    - name: #Element entry name, and its type is String.
      description: #Element entry description, and its type is String.
      readonly: #Whether the element entry is read-only, the value is true or false.
      placeholder: #The placeholder of Element entry, and its type is String.
      value: #Default values for entries and its type is String.
      required: #Is the entry required, and the value is true or false.
      secretCode: #Whether it is displayed in cryptograph mode, for setting a password and the value is true or false.
      reference: #Is it the reference and the value is true or false.
      referenceKey: #The value referenced, which corresponds to the corresponding docker-compose.yml file and the type is String.
      validation: #Check the entry data, see below for details.
      - !!com.supermap.imanager.commontypes.RuleRegexValidatio #Check Class.
        regex: #The property is determined by the class that is currently used.
        message: #The property is determined by the class that is currently used.
appSetDetailPage: #Process the compose application details page.
  description: #Description in the upper left corner of the page.
  serviceTemplates: #The information template to be displayed for each service on the page.
  - serviceName: #The name of the service corresponding to the address to be displayed on the page, through which the corresponding docker container is found.
    multiInternalPort: #Whether multiple exposed ports exist, with a value of true or false.
    scale: #Specifies whether the node can scale dynamically, with a value of true or false.
    autoScale: #Specifies whether the node can scale automatically and dynamically, with a value of true or false.
    FTP: #Specifies whether the node is an FTP container, with a value of true or false.
    showFTP: # Specifies whether the node displays the "upload data" button with a value of true or false.
    targetServiceName: #The targetServiceName, which is consistent with the serviceName of the target service, and the type is String.
    containerPortFilter: #Container port filter. If a container exposes several ports, you can filter through the field. Only one port is shown at the "container port" in figure 3. The type is List&lt;String&gt;.
    urlTemplate: #url template
      - urlTemplate: #The type is String
        internalPort: #Container internal port and its type is String
    portTemplate: #The template that the port displays and its type is String.
    specifyExposedPort: #Whether the current container exposes the specified port, the value is true or false.
    specifyExposedPortLabelKey: #The external port corresponding to which internal port is currenty exposed adnd its type is String.
    description: #Description information for the container, and the type is String.

Type in createAppSetPage has the following values:

text：String type, which is used to create pages that need input strings
port：It is used to the palce where the page needs input ports to be created.
replicate：It refers to the “service mode” when multiple machines are created. When the type is replicate, the first value of item can only be replicated or global. When the value is replicated, the value of its “copy number” is determined by the second value. See the following example.

- type: replicate
  position: advanced
  serviceName: namenode
  display: false
  item:
    - value: replicated
    - value: 1
- type: replicate
  position: advanced
  serviceName: datanode
  item:
    - readonly: true
      value: global

placement：Refers to the “constraint” when multiple machines are created. When type is placement, its item value can only be none. Please refer to the following example.

- type: placement
  position: advanced
  serviceName: spark-worker
  placementIndex: 0
  item:
    - value: none

A special description of item in createAppSetPage:

In the compose application creation page, enter the name of the entry, as shown in Figure 2 for “MySQL name”, which does not need to be defined in the rule.yml file, and the entry for “private repository address” does not need to be included int rule.yml file, except for the name entry.

A special description of validation in createAppSetPage:

Currently offers com.supermap.imanager.commontypes.RuleRegexValidatio(calibration of a regular expression) and com.supermap.imanager.commontypes.RuleStringLengthValidatio(check string). The validating class for the regular expression provides the regex and message attributes, and the validating class for the string provides the stringLength, stringLengthMin, stringLengthMax and message attributes. See the following example:

validation：
  - !!com.supermap.imanager.commontypes.RuleStringLengthValidatio
    stringLength：true
    stringLengthMin：20
    stringLengthMax：100
    message："The length can only be between 20 and 100"

The following is a detailed description of the rule.yml file for the Compose application “MySQL” that comes with the SuperMap iManager product:

version: "1"
appSetListPage: #See Figure 1
  serviceTemplate:
    serviceName: phpmyadmin
    urlTemplate: "http:#%1$s:%2$s"
    appSetBaseName: mysql #The containers "mysql3_mysqldb_1" and "mysql3_phpmyadmin_1" created in Figure 2 are prefixed with "mysql".
createAppSetPage: #See Figure 12
  - type: text
    position: basic
    item: #The entry "set the root user password"
      - name: "ROOT_PASSWORD" #Be consistent with the docker-compose.yml file
        description: "set the root user password" #In the left column of figure 2, "set the root user password"
        readonly: false #Instead of read-only, you can fill in the password as shown
        placeholder: "e.g. root" #The default placeholder is "e.g. root", before entering the password
        required: true
        secretCode: true #The password entered is displayed as ciphertext
  - type: port
    position: advanced
    item: #The entry "mysqldb external port"
      - name: "MYSQL_EXPOSE_PORT" #The "host port" corresponding to mysqldb is consistent with the docker-compose.yml file
        description: "mysqldb external port"
        placeholder: "e.g. 3306"
        validation:
          - !!com.supermap.imanager.commontypes.RuleRegexValidation
            regex: '^(102[4-9]|10[3-9]\d{1}|1[1-9]\d{2}|[2-9]\d{3}|[1-5]\d{4}|6[0-4]\d{3}|65[0-4]\d{2}|655[0-2]\d{1}|6553[0-5])$'
            message: "Ports can only be between 1024-65535" #The prompt message appears when the input is not in the current regular expression range
      - name: "MYSQL_CONTAINER_PORT" #The "container port" corresponding to mysqldb is consistent with the docker-compose.yml file.
        value: 3306 # Uneditabe 3306 in the figure
  - type: port
    item: #The entry "phpmyadmin external port"
      - name: "PHPMYADMIN_EXPOSE_PORT"
        description: "phpmyadmin external port"
        placeholder: "e.g. 80"
        validation:
          - !!com.supermap.imanager.commontypes.RuleRegexValidation
            regex: '^(102[4-9]|10[3-9]\d{1}|1[1-9]\d{2}|[2-9]\d{3}|[1-5]\d{4}|6[0-4]\d{3}|65[0-4]\d{2}|655[0-2]\d{1}|6553[0-5])$'
            message: "Ports can only be between 1024-65535"
      - name: "PHPMYADMIN_CONTAINER_PORT"
        value: 80
appSetDetailPage: #See Figure 3
  description: "Simple instructions：\n 1. MySQL uses the official 5.7.12 version of the mirror\n 2. You can view the database in your browser through phpmyadmin \n 3. You can connect to the database remotely via IP and port exposed by the MySQL container \n 4. The root user password of MySQL：" #See detailed information on the upper left corner
  serviceTemplates:
    - serviceName: mysqldb #Be consistent with the service in the docker-compose.yml file
      urlTemplate: "jdbc:mysql:#%1$s:%2$s" #Corresponding to the "address" in Figure 3
      portTemplate: "%1$s"#Corresponding to the "container port" in Figure 3
      description: MySQL Database #Corresponding to the "container description" in Figure 3
    - serviceName: phpmyadmin
      urlTemplate: "http:#%1$s:%2$s"
      portTemplate: "%1$s"
      description: MySQL's WEB client

Advanced configuration

You can map the name of your own Compose application by ‘list.json(list_en.json)’ file. The order in the ‘list.json(list_en.json)’ file determines the order in which compose application is displayed on the UI. Please follow the steps below to get the ‘list.json’ and ‘list_en.json’ file:
- Excute the command to fine the imanager-config mount path:
```
docker inspect --format '{{(index .Mounts 3).Source}}' imanager
```
- Go to the path below, go find the ‘list.json’ and ‘list_en.json’ file. ({imgr-config-path} is the imanager-config mount path from the previous step.)
```
cd {imgr-config-path}/appSet
```
The docker-compose.yml file supports the use of .env file and can be placed in the directory where the docker-compose.yml file is located.
If you want your custom compose application to support multi-machine deployment, you can just need to create a new folder called “multi-node’ under the corresponding standalone folder with the same contents as the standalone:docker-compose.yml、rule.yml and .env file(as needed).