[17.0.0.1 and later]

Registering Liberty servers on Docker with IBM Cloud Product Insights

You can register IBM WebSphere Liberty servers that are running on Docker with Bluemix® Product Insights to report server registration and usage and other information, such as number of active WebSphere Liberty servers, host location of each server, product edition and version of each server, and how busy each server is.

Before you begin

IBM Cloud Product Insights requires WebSphere Application Server Liberty version 17.0.0.1 or later.

The Liberty Docker builds include a pull of the most version of the WebSphere Liberty Docker image from Docker hub. The Liberty Docker Hub images include an ILAN license, meaning that they are no-cost, non-supported, and non-warranted versions of the product. To update the license to a supported product, see Upgrading the image from Docker Hub to a production image.

Before you connect an IBM WebSphere Liberty server instance to Product Insights, you must have an IBM Cloud account and create the service in an organization and space. Follow the getting started steps to set up an account and allocate the Product Insights service. Make a note of the API host and API key that is described in the instructions.

Configuring your WebSphere Liberty servers on Docker requires either a Linux machine or a virtual machine with Docker installed.

About this task

After you define the Liberty collective and create the Docker image in a Docker container, use the Deploy tool to install the image on a Docker host within the collective.

Procedure

  1. Build the Docker image.
    1. Configure the connection to the Product Insights service. In theserver.xml file of the Liberty server, configure the connection to the Product Insights service. Substitute <apiHost> with the API host for your Product Insights service. Substitute <apiKey> with the API key for your service.
      <server>
          <featureManager>
             <feature>productInsights-1.0</feature>
          </featureManager>
          <productInsights url="<apiHost>" apiKey="<apiKey>" sslRef="productInsightsSSL"      
               groups="DockerImages"/>
          <keyStore id="productInsightsKeyStore" location="/config/digicert.jks" type="JKS"/>
          <ssl id="productInsightsSSL"
               keyStoreRef="productInsightsKeyStore"
               trustStoreRef="productInsightsKeyStore"
               sslProtocol="TLSv1.2"/>
      </server>
      Note: If the machine that runs the Docker container connects to the Product Insights service through a gateway or proxy server, the configuration is slightly different. For more information, see Use a gateway or proxy server.
    2. Create an installation Dockerfile. In the same directory as the server.xml file, create a Dockerfile that installs the Liberty image, the productInsights-1.0 Liberty feature, and the IBM Cloud digicert.jks certificate file. The following Dockerfile pulls the websphere-liberty:webProfile7 image from Docker Hub and uses that version of Liberty to build the new image. For other Liberty Docker images that you can install, see the websphere-liberty repository on Docker Hub.
      FROM websphere-liberty:webProfile7
      COPY server.xml /config/
      RUN apt-get update \
          && apt-get install -y --no-install-recommends unzip curl \
          && rm -rf /var/lib/apt/lists/*
      RUN installUtility install --acceptLicense productInsights-1.0\
          && rm -rf /output/workarea /output/logs
      RUN cd /opt/ibm/wlp/usr/servers/defaultServer \
          && curl -O https://wlpcfg.ng.bluemix.net/productinsights/digicert.jks
    3. Build the Docker image. Build the Docker image by running the docker build command. The machine that you build the Docker image from must have access to the internet because it needs to download the Liberty Docker image, the productInsights-1.0 Liberty feature, and the required IBM Cloud digicert.jks certificate.
      docker build -t liberty-product-insights-example
  2. Run the image in a Docker container.
    1. Run an instance of the Docker image. To run an instance of the Docker image, use the name of the application that is hosted on the Liberty server container. The following example illustrates the best practice for naming.
      docker run -d -e CONTAINER_HOST='myApplication' liberty-product-insights-example
      Note: The default host name that is reported to Product Insights for the running server instance is the container name, which is reassigned each time a Docker image is run or scaled. To be able to consistently track metrics for a server, you must override the default host name value by setting a value for the CONTAINER_HOST environment variable.
    2. Run multiple instances of the Docker image. To run multiple instances of the Docker image for the same application, use the same value for CONTAINER_HOST for each instance. When registration and usage data that corresponds to the CONTAINER_HOST is sent to the Product Insights service, the service combines the information as if it came from a single instance so that you can see all usage that is associated with the application.
      Note: To optionally override the server name, set the CONTAINER_NAME environment variable. If this variable is not set, all images report defaultServer as the server name to the Product Insights Service.
      docker run -d -e CONTAINER_HOST=' myApplication' -e CONTAINER_NAME=' myServerName' liberty-product-insights-example
  3. Verify registration with IBM Cloud Product Insights.
    1. Find the container ID by running the docker ps command.
      docker ps
    2. Attach STDIN to the Docker container through bash so that you can interact with the Docker container file system.
      docker exec -it <containerId> bash
    3. Verify that the server was registered with the Product Insights service by checking the Liberty logs. In the /logs directory, open the messages.log file and look for the following message.
      CWWKR0400I: The server was registered with the IBM Cloud Product Insights service on the specified URL <apiHost>.
    4. In your browser, go to your Product Insights service dashboard on IBM Cloud to view the newly registered server.

Results

Your IBM WebSphere Liberty servers that are running on Docker with IBM Cloud Product Insights are registered to support server registration and usage.


Icon that indicates the type of topic Task topic

File name: twlp_docker_product_insights.html