LiveView: Creating Docker Images

Contents

Docker Desktop Requirements
Load a LiveView Fragment Project
Specify an Exact Port Number
Maven-Install the Fragment
Create a StreamBase Application Project
Add Dependency
Build and Install the Docker Image
Confirm Local Docker Image
Next Steps

This tutorial page describes how to use StreamBase Studio and, optionally, the mvn command to build a runnable archive of a StreamBase Application with LiveView fragment, then automatically package and install that archive into a Docker container.

Docker is a third-party technology used to create, deploy, and run applications by using containers of running applications across a network or the cloud. Describing Docker is beyond the scope of this document. Docker background and usage can be found on its website.

On this tutorial page, you will:

  • Configure a StreamBase Application running the Hello LiveView fragment.

    • If you prefer to start with an Application running an EventFlow fragment, open this page instead.

  • Use StreamBase Studio or the mvn command to build a Docker-ready Image for that application.

  • Automatically install this image into a Docker container managed locally in Docker Desktop.

Docker Desktop Requirements

To configure a StreamBase application for Docker, you must have:

  • StreamBase Studio.

  • Docker Desktop for Mac or Windows installed and running.

  • A currently active Internet connection.

Third-Party Software

When you obtain third-party software or services, it is your responsibility to ensure that you understand the license terms associated with such third-party software or services and comply with such terms.

See the Docker Desktop Notes on the EventFlow in Docker page to understand the Docker Desktop requirements.

Important

You must configure Docker Desktop to run with at least as much local system memory as your StreamBase Application requires, plus local Docker overhead. LiveView fragments are especially sensitive to this setting. You will NOT be able to run even the smallest LiveView fragment with the default Docker Desktop settings.

In general, look at the LiveView fragment's LiveView engine configuration file for the -Xmx setting in the LDMEngine>jvmArgs array. Configure Docker Desktop to use your -Xmx value plus about 2 GB. For all LiveView fragments, including the one in this tutorial, open Docker Desktop's Preferences dialog, open the Resources menu, and change the Memory slider to at least 5.00 GB. Set the CPUs slider to the number of cores in your machine's CPU or fewer. These requirements are cumulative for every container you try to run at the same time.

Load a LiveView Fragment Project

  1. From StreamBase Studio, select File>Import Samples and Community Content.

    In the search field for the StreamBase Sample Importer dialog, type hello to narrow the list of options. Select the Hello LiveView search result, then click Import Now.

  2. It may take some time for Studio to build the loaded project the first time, as it resolves and copies Maven dependencies. The project is ready when there are no red marks on any folder or file of the sample_lv_sample_helloliveview project in the Project Explorer view.

Specify an Exact Port Number

In a change from previous releases, LiveView fragments running in a Docker container are no longer automatically assigned the client API listening port 11080 by default. Thus, starting with versions 10.6.0, you must explicitly assign a listening port for each LiveView fragment that will run inside a Docker container.

Do this by including a simple ldmclientapilistener configuration file in the fragment project's src/main/configurations folder in StreamBase Studio. For example, copy the following into a file named ldmapilisten.conf in the configurations folder for the sample_lv_sample_helloliveview project. 

name = "ldmapilisten"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
version = "1.0.0"
configuration = {
    ClientAPIListener = {
        portNumber = 11000
    }
}

This tutorial uses port 11000 to easily distinguish it from any non-Docker LiveView fragments you may have running locally.

Maven-Install the Fragment

You must use Maven to build and install the fragment project before packaging and installing the StreamBase Application project that contains the fragment.

Note

This step is not required before packaging application projects for regular use without Docker. In that case, the packaging wizard, described below, installs all dependent fragments as part of the packaging.

Using the mvn Command

If you are comfortable working at the command prompt, follow these steps:

  1. At the command prompt, navigate to the workspace location for this sample_lv_sample_helloliveview project.

  2. Run the following command: 

    mvn clean install -DskipTests

  3. Look for the BUILD SUCCESS message.

  4. Proceed to the next section.

Using StreamBase Studio

If you prefer to work in StreamBase Studio, follow these steps:

  1. In the Project Explorer view, select and right-click the sample_lv_sample_helloliveview folder. Select Run As>Maven build...

    (Be sure to select the Maven build... option with the three dots. If you inadvertently run the other Maven build option and it fails, come back to this point and start over.)

  2. In the Edit Configuration and launch dialog:

    • In the Goals field, enter clean install

    • Select the Skip Tests and Resolve Workspace artifacts checkboxes.

    • Click Apply, then click Run.

  3. Keep an eye on the Console view as messages scroll by. Look for the BUILD SUCCESS message. 

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.980 s
[INFO] Finished at: 2020-05-16T08:12:18-04:00
[INFO] ------------------------------------------------------------------------

  4. Proceed to the next section.

Create a StreamBase Application Project

The steps in this section create a StreamBase Application project with its Docker option enabled.

  1. Optional. Open the sample_lv_sample_helloliveview project's /src/main/eventflow folder to make a note of the Group ID used by the LiveView fragment project. We will use a portion of the same Group ID when creating the Application project.

  2. Select File>New>StreamBase Project.

  3. In the StreamBase Project dialog, enter a project name. This tutorial uses docker_hellolv throughout.

  4. Select the StreamBase Application option.

  5. Click Next. (If you click Finish in error, start over.)

  6. In the Configure Maven Artifact panel, change the value of the Group ID to com.tibco.ldm.sample to match the first part of the Group ID of the fragment sample as determined in step 1. (You are not required to use the same Group ID for an Application project as for its dependent fragment projects, but doing this brings clarity to the process.)

    Select the Enable Docker support check box. This is the entire difference between building an application that runs locally and one that runs in a Docker container.

    Optional. This tutorial suggests changing the Version number to 1.0.0 to save some typing with upcoming Docker commands, but that is not required.

  7. Click Next.

  8. Optional. Make changes In the Archetype Properties panel as needed, following the guidelines in the table below.

    Property Default Description
    description My Application Enter any text to characterize this application and distinguish it from other applications in your network. This string ends up in the <description> element of your application project's pom.xml file.
    testnodes A,B,C Specify one or more node names for test nodes that are started when you run Maven Test or another Maven goal that requires Test. You can reduce project build time at the expense of test coverage by replacing the default three nodes, A,B,C with just A.
    dockerDomain example.com Specify a domain name that will allow your Docker containers to communicate with each other. The domain name you specify here is configured into a TrustedHosts configuration file for this application. This allows all StreamBase Runtime nodes to participate in the same domain as the Docker containers, which allows node-to-node communication to occur without user authentication for nodes in the same Docker network. Members of this domain will be trusted hosts for each other.

    To take advantage of this feature, use the --network and --hostname options in your docker run command, as described in Configuring Multiple Docker Containers.

    sample false This property only appears when you select the Kubernetes and/or Helm checkboxes on the Configure Maven Artifact panel. TIBCO personnel only can change this value to true when configuring a sample to be delivered to the tibco-streaming-samples repository on GitHub. The true setting performs two actions:

    • The <artifact> child element of the <parent> element in the application's pom.xml file is filled with ep-application-docker-samples instead of ep-application-docker, which allows the sample to build correctly with GitHub's continuous integration system.

    • Each configuration, Markdown, Dockerfile, and POM file in the project is prepended with a TIBCO-specific copyright header section.

  9. Click Finish. (Also click OK if prompted with a follow-up dialog.)

    This creates a new project named docker_hellolv in the Project Explorer view.

Add Dependency

The next step is to configure docker_hellolv application project to be aware of its Maven dependency on the sample_lv_sample_helloliveview LiveView fragment project.

  1. Select the docker_hellolv project name in the Project Explorer view. Right-click and select StreamBase>Manage Project Dependencies.

  2. Studio shows a message dialog like the following.

    When you click OK, Studio performs the following actions:

    • Opens the POM Editor for the application project's pom.xml file.

    • Switches to the Dependencies tab of the POM Editor.

    • Opens the Add Dependency dialog,

  3. In the Add Dependency dialog, type hello in the Enter groupId filter field.

  4. The dialog shows two entries that match, the current application project and the fragment project you loaded in above. Select the fragment project, and open the arrowhead on its left.

    If there is more than one ep-liveview-fragment entry (perhaps because your local Maven repository has artifacts from previous StreamBase releases), select the entry whose version number matches the current StreamBase release.

    Click OK.

  5. Confirm that the pom.xml file for the docker_hellolv project is saved.

Build and Install the Docker Image

Perform a Maven-install operation to package your StreamBase Application project into an archive file, then package the archive into a Docker container image, then install the container image into your local Docker Desktop environment.

Using the mvn Command

If you are comfortable working at the command prompt, follow these steps to build and install your Docker image:

  1. At the command prompt, navigate to the workspace location for this docker_hellolv project.

  2. Run this command: 

    mvn clean install -DskipTests

  3. Look for the BUILD SUCCESS message.

  4. Proceed to Confirm Local Docker Image.

Using StreamBase Studio

If you prefer to work in the context of StreamBase Studio, follow these steps to build and install your Docker image:

  1. Make sure your development machine is connected to the Internet. This procedure runs best with no settings.xml file in your local ~/.m2 directory, or with a minimal one.

  2. Important! Make sure your Docker for Windows or Docker for Mac installation is currently running.

  3. In the Project Explorer view, select and right-click the docker_hellolv folder. Select StreamBase>Create StreamBase Application Archive.

  4. This opens the Package an Application dialog.

  5. There is nothing to configure on this dialog (unless something went wrong in a previous run), so click Package Application.

  6. Keep an eye on the Output of packaging steps (which has the same content as the Console view) as messages scroll by. Look for one BUILD SUCCESS message for the fragment included in the application, plus a final BUILD SUCCESS message for the application.

  7. Proceed to the next section.

Confirm Local Docker Image

To confirm success, open a StreamBase Command Prompt (Windows) or a StreamBase-configured Terminal window (macOS).

Get a list of your currently installed Docker images using the docker images command: 

REPOSITORY       TAG      IMAGE ID         CREATED             SIZE
docker_hellolv   1.0.0    08277a6d9592     23 minutes ago      848MB
sbrt-base        10.6.0   c39719f31fba     2 hours ago         828MB

Your images list may include other Docker images from running the Docker Getting Started tutorial, from the EventFlow fragment tutorial, or from Kubernetes setup. The three images listed above are the ones generated by the steps on this page.

Next Steps

This concludes the work in StreamBase Studio or the command prompt to generate the StreamBase Application archive for a LiveView fragment and package it into a Docker image in your local Docker environment.

The tutorial continues:

  • On the next page to demonstrate using Docker commands to run this image and communicate with the containerized StreamBase Application. Click Next at the bottom right of this page.

  • On the the page after next, to connect to the running containerized Hello LiveView sample with a web browser.

  • You can also jump back to go through similar steps as this page, except for an EventFlow fragment.