EventFlow: Creating Docker Images

Contents

Docker Desktop Requirements
Load an EventFlow Fragment Project
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 EventFlow 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 a simple EventFlow fragment.

    • If you prefer to start with an Application running a LiveView 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.

To run the command prompt steps on this page, you must open a StreamBase Command Prompt on Windows or a StreamBase-Configured Shell on macOS or Linux.

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.

Docker Desktop Notes

When configuring Docker Desktop for these tutorial pages, there is no need to enable the Kubernetes option at this point, but you can if you prefer.

The steps on this and the next few pages were tested in June, 2020 with release 2.3.0.3 from the Stable release channel of Docker Desktop for Windows and Docker Desktop for Mac. Earlier Docker Desktop releases and other Docker client solutions may work, but are explicitly not supported — including Docker Toolbox. Later releases of Docker Desktop are expected to work.

Docker Desktop for Windows requires 64-bit Windows 10 Pro or Enterprise with Microsoft Hyper-V available and enabled. Note that installing Hyper-V conflicts with VMware Workstation or Oracle VirtualBox on the same Windows computer, and the Docker Desktop installer disables those products if encountered. This is because Windows 10 allows only one virtualization hypervisor to run at the same time. See Docker's site for any further requirements of Docker Desktop for Windows.

Recent releases of Docker Desktop for Windows also support using Linux containers in the Windows Subsystem for Linux 2 as the Docker hypervisor. This is an advanced solution not yet tested.

Docker Desktop for Mac requires macOS 10.13 (High Sierra), 10.14 (Mojave), or 10.15 (Catalina). The Mac hardware must be a 2010 model or later. See Docker's site for any further requirements of Docker Desktop for Mac.

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. Simple EventFlow fragments like the one used in this tutorial run fine with the Docker Desktop default setting of about 2 GB, and the same is true of most samples included with StreamBase Studio. If your EventFlow fragment includes a configuration file with a jvmArgs array and -Xmx setting, configure Docker Desktop to use your -Xmx value plus about 2 GB. These requirements are cumulative for every container you try to run at the same time.

Load an EventFlow Fragment Project

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

    In the search field for the StreamBase Sample Importer dialog, type first to narrow the list of options. Select the Getting Started Guide tutorial 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_firstapp project in the Project Explorer view.

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_firstapp 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_firstapp 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_firstapp project's /src/main/eventflow folder to make a note of the Group ID used by the EventFlow fragment project, which is com.tibco.sb.sample. We will use the same Group ID in creating the Application project.

  2. Select File>New>StreamBase Project.

  3. In the StreamBase Project dialog, enter a project name. This tutorial uses docker_1st 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.sb.sample to match 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.

    Click Next.

    • If the Enable Docker support option is checked, then the docker files are generated.

    • If the Use Kubernetes for container orchestration option is checked, then the YAML file for Kubernetes generates in src/main/kubernetes folder and security.conf is updated for the default Kubernetes network name.

    • If the Use Helm as packaging type option is checked, then the YAML file for Helm Chart generates in src/main/helm folder and Kubernetes files get generated in the Helm structure.

  7. 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.

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

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

Add Dependency

The next step is to configure docker_1st application project to be aware of its Maven dependency on the firstapp EventFlow fragment project.

  1. Select the docker_1st 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 firstapp in the Enter groupId filter field.

  4. Select com.tibco.sb.sample    firstapp in the Search Results field and open the arrowhead on its left.

    If there is more than one ep-eventflow-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_1st 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_1st 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_1st 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_1st   1.0.0    7133e7ec1a4c     23 minutes ago      828MB
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 LiveView 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 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 page after next, to connect to the running StreamBase application with client commands to send and receive tuples.

  • You can also jump ahead to go through similar steps as this page, except for a LiveView fragment.