ibmcom/ace

By ibmcom

Updated about 4 years ago

Official IBM App Connect Enterprise for Developers image

Image

1M+

DEPRECATED - This is no longer being developed.

The replacement is now available at https://www.ibm.com/docs/en/app-connect/12.0?topic=cacerid-building-sample-app-connect-enterprise-image-using-docker

Overview

This repository contains some Dockerfiles and some scripts which demonstrate a way in which you might run IBM App Connect Enterprise in a Docker container.

The base image contains a full installation of IBM App Connect Enterprise for Developers Version 11.0.0.9, as well as some system configuration and user creation.

The source to these images can be found under the releases of https://github.com/ot4i/ace-docker. Note that the latest image may not align with latest code in GitHub (master branch)

Docker Hub

A pre-built version of the App Connect Enterprise image is available with the following tags:

  • 11.0.0.0
  • 11.0.0.2
  • 11.0.0.3
  • 11.0.0.4
  • 11.0.0.5-amd64
  • 11.0.0.5.1-amd64
  • 11.0.0.6-amd64
  • 11.0.0.6.1-amd64
  • 11.0.0.7-r1-amd64
  • 11.0.0.8-r1-amd64
  • 11.0.0.9-r1-amd64, latest

Dockerfile on GitHub

Usage

Accepting the License

In order to use the image, it is necessary to accept the terms of the IBM App Connect Enterprise license. This is achieved by specifying the environment variable LICENSE equal to accept when running the image. You can also view the license terms by setting this variable to view. Failure to set the variable will result in the termination of the container with a usage statement. You can view the license in a different language by also setting the LANG environment variable.

Running the image

To run a container using this image with default configuration and these settings:

  • ACE server name ACESERVER
  • listener for ACE web ui on port 7600
  • listener for ACE HTTP on port 7600 run the following command:

docker run --name aceserver -p 7600:7600 -p 7800:7800 -p 7843:7843 --env LICENSE=accept --env ACE_SERVER_NAME=ACESERVER ibmcom/ace:latest

Once the console shows that the integration server is listening on port 7600, you can go to the App Connect Enterprise UI at http://localhost:7600/. To stop the container, run docker stop aceserver and the container will shut down cleanly, stopping the integration server.

Environment variables supported by this image
  • LICENSE - Set this to accept to agree to the App Connect Enterprise license. If you wish to see the license you can set this to view.
  • LANG - Set this to the language you would like the license to be printed in.
  • LOG_FORMAT - Set this to change the format of the logs which are printed on the container's stdout. Set to "json" to use JSON format (JSON object per line); set to "basic" to use a simple human-readable format. Defaults to "basic".
  • USE_QMGR - Set to true to start a Queue Manager and set the Integration Server to use it.
  • ACE_ENABLE_METRICS - Set this to true to generate Prometheus metrics for your Integration Server.
  • ACE_SERVER_NAME - Set this to the name you want your Integration Server to run with.
  • ACE_TRUSTSTORE_PASSWORD - Set this to the password you wish to use for the trust store (if using one).
  • ACE_KEYSTORE_PASSWORD - Set this to the password you wish to use for the key store (if using one).
  • ACE_ADMIN_SERVER_SECURITY - Set to true if you intend to secure your Integration Server using SSL.
  • ACE_ADMIN_SERVER_NAME - Set this to the DNS name of your Integration Server for SSL SAN checking.
  • ACE_ADMIN_SERVER_CA - Set this to your Integration Server SSL CA certificate.
  • ACE_ADMIN_SERVER_CERT - Set this to your Integration Server SSL certificate.
  • ACE_ADMIN_SERVER_KEY - Set this to your Integration Server SSL key certificate.

How to dynamically configure the App Connect Enterprise Integration Server

To enable dynamic configuration of the Integration Server, this setup supports configuration injected into the image as files.

Before the Integration Server starts, the container is checked for the folder /home/aceuser/initial-config. For each folder in /home/aceuser/initial-config a script called ace_config_{folder-name}.sh will be run to process the information in the folder. Shell scripts are supplied for the list of folders below, but you can extend this mechanism by adding your own folders and associated shell scripts.

  • Note: The work dir for the Integration Server in the image is /home/aceuser/ace-server.
  • Note: An example initial-config directory with data can be found in the sample folder, as well as the [command on how to mount it when running the image]((sample/README.md#run-the-sample-image).

You can mount the following file structure at /home/aceuser/initial-config. Missing folders will be skipped, but empty folders will cause an error:

  • /home/aceuser/initial-config/keystore
    • A text file containing a certificate file in PEM format. This will be imported into the keystore file, along with the private key. The filename must be the alias for the certificate in the keystore, with the suffix .crt. The alias must not contain any whitespace characters.
    • A text file containing a private key file in PEM format. This will be imported into the keystore file, along with the certificate. The filename must be the alias for the certificate in the keystore, with the suffix .key.
    • If the private key is encrypted, then the passphrase may be specified in a file with the filename of alias with the suffix .pass.
    • The keystore file that will be created for these files needs a password. You must set the keystore password using the environment variable ACE_KEYSTORE_PASSWORD.
    • You can place multiple sets of files, each with a different file name/alias; each .crt file must have an associated .key file, and a .pass file must be present if the private key has a passphrase.
  • /home/aceuser/initial-config/odbcini
    • A text file called odbc.ini. This must be an odbc.ini file suitable for the Integration Server to use when connecting to a database. This will be copied to /home/aceuser/ace-server/odbc.ini.
  • /home/aceuser/initial-config/policy
    • A set of .policyxml files, each with the suffix .policyxml, and a single policy.descriptor file. These will be copied to /home/aceuser/ace-server/overrides/DefaultPolicies/. They should be specified in the server.conf.yaml section in order to be used.
  • /home/aceuser/initial-config/serverconf
    • A text file called server.conf.yaml that contains a server.conf.yaml overrides file. This will be copied to /home/aceuser/ace-server/overrides/server.conf.yaml
  • /home/aceuser/initial-config/setdbparms
    • For any parameters that need to be set via mqsisetdbparms include a text file called setdbparms.txt. This supports 2 formats:
      # Lines starting with a "#" are ignored# Each line which starts mqsisetdbparms will be run as written # Alternatively each line should specify the <resource> <userId> <password>, separated by a single space# Each line will be processed by calling...#   mqsisetdbparms ${ACE_SERVER_NAME} -n <resource> -u <userId> -p <password>resource1 user1 password1resource2 user2 password2mqsisetdbparms -w /home/aceuser/ace-server -n salesforce::SecurityIdentity -u myUsername -p myPassword -c myClientID -s myClientSecret
      
  • /home/aceuser/initial-config/truststore
    • A text file containing a certificate file in PEM format. This will be imported into the truststore file as a trusted Certificate Authority's certificate. The filename must be the alias for the certificate in the keystore, with the suffix .crt. The alias must not contain any whitespace characters.
    • The truststore file that will be created for these files needs a password. You must set a truststore password using the environment variable ACE_TRUSTSTORE_PASSWORD
    • You can place multiple files, each with a different file name/alias.
  • /home/aceuser/initial-config/webusers
    • A text file called admin-users.txt. It contains a list of users to be created as admin users using the command mqsiwebuseradmin. These users will have READ, WRITE and EXECUTE access on the Integration Server. The file has the following format:
      # Lines starting with a "#" are ignored# Each line should specify the <user> <password>, separated by a single space# Each user will have "READ", "WRITE" and "EXECUTE" access on the integration server# Each line will be processed by calling...#   mqsiwebuseradmin -w /home/aceuser/ace-server -c -u <user> -a <password> -r adminadmin1 password1admin2 password2
      
    • A text file called operator-users.txt. It contains a list of users to be created as operator users using the command mqsiwebuseradmin. These users will have READ and EXECUTE access on the Integration Server. The file has the following format:
      # Lines starting with a "#" are ignored# Each line should specify the <user> <password>, separated by a single space# Each user will have "READ" and "EXECUTE" access on the integration server# Each line will be processed by calling...#   mqsiwebuseradmin -w /home/aceuser/ace-server -c -u <user> -a <password> -r operatoroperator1 password1operator2 password2
      
    • A text file called editor-users.txt. It contains a list of users to be created as editor users using the command mqsiwebuseradmin. These users will have READ and WRITE access on the Integration Server. The file has the following format:
      # Lines starting with a "#" are ignored# Each line should specify the <user> <password>, separated by a single space# Each user will have "READ" and "WRITE" access on the integration server# Each line will be processed by calling...#   mqsiwebuseradmin -w /home/aceuser/ace-server -c -u <user> -a <password> -r editoreditor1 password1editor2 password2
      
    • A text file called audit-users.txt. It contains a list of users to be created as audit users using the command mqsiwebuseradmin. These users will have READ access on the Integration Server. The file has the following format:
      # Lines starting with a "#" are ignored# Each line should specify the <user> <password>, separated by a single space# Each user will have "READ" access on the integration server# Each line will be processed by calling...#   mqsiwebuseradmin -w /home/aceuser/ace-server -c -u <user> -a <password> -r auditaudit1 password1audit2 password2
      
    • A text file called viewer-users.txt. It contains a list of users to be created as viewer users using the command mqsiwebuseradmin. These users will have READ access on the Integration Server. The file has the following format:
      # Lines starting with a "#" are ignored# Each line should specify the <user> <password>, separated by a single space# Each user will have "READ" access on the integration server# Each line will be processed by calling...#   mqsiwebuseradmin -w /home/aceuser/ace-server -c -u <user> -a <password> -r viewerviewer1 password1viewer2 password2
      
  • /home/aceuser/initial-config/mqsc
    • A text file called config.mqsc. It contains a list of mqsc commands which will be processed on start by runmqsc command. Further details can be found in the MQ Knowledge Center
  • /home/aceuser/initial-config/agent
    • A json file called 'switch.json' containing configuration information for the switch, this will be copied into the appropriate iibswitch directory
    • A json file called 'agentx.json' containing configuration information for the agent connectivity, this will be copied into the appropriate iibswitch directory
    • A json file called 'agentc.json' containing configuration information for the agent connectivity, this will be copied into the appropriate iibswitch directory
    • A json file called 'agentp.json' containing configuration information for the agent connectivity, this will be copied into the appropriate iibswitch directory
  • /home/aceuser/initial-config/extensions
    • A zip file called extensions.zip will be extracted into the directory /home/aceuser/ace-server/extensions. This allows you to place extra files into a directory you can then reference in, for example, the server.conf.yaml
  • /home/aceuser/initial-config/ssl
    • A pem file called 'ca.crt' will be extracted into the directory /home/aceuser/ace-server/ssl
    • A pem file called 'tls.key' will be extracted into the directory /home/aceuser/ace-server/ssl
    • A pem file called 'tls.cert' will be extracted into the directory /home/aceuser/ace-server/ssl

Logging

The logs from the integration server running within the container will log to standard out. The log entries can be output in two formats:

  • basic: human-headable for use in development when using docker logs or kubectl logs
  • json: for pushing into ELK stack for searching and visualising in Kibana

The output format is controlled by the LOG_FORMAT environment variable.

A sample Kibana dashboard is available from GitHub

Monitoring

The accounting and statistics feature in IBM App Connect Enterprise provides the component level data with detailed insight into the running message flows to enabled problem determination, profiling, capacity planning, situation alert monitoring and charge-back modelling.

A Prometheus exporter runs on port 9483 if ACE_ENABLE_METRICS is set to true - the exporter listens for accounting and statistics, and resource statistics, data on a websocket from the integration server, then aggregates this data to make available to Prometheus when requested.

A sample Grafana dashboard is available from GitHub

License

The Dockerfile and associated scripts are licensed under the Eclipse Public License 2.0. Licenses for the products installed within the images are as follows:

  • IBM App Connect Enterprise for Developers is licensed under the IBM International License Agreement for Non-Warranted Programs. This license may be viewed from the image using the LICENSE=view environment variable as described above.
  • License information for Ubuntu packages may be found in /usr/share/doc/${package}/copyright

Note that the IBM App Connect Enterprise for Developers license does not permit further distribution.

Copyright

© Copyright IBM Corporation 2015, 2019

Docker Pull Command

docker pull ibmcom/ace