Creating and Running Docker Images

This tutorial describes how to use StreamBase Studio to build a Docker image from a StreamBase application, and deploy the image to Docker. Docker is a third-party application used to create, deploy, and run applications by using containers of information across a network or the cloud. Describing Docker is beyond the scope of this document. Docker usage can be found on its website.

In this tutorial, you will:

  • Configure a simple StreamBase Application.

  • Use StreamBase Studio to build a Docker Image for the application.

  • Run this image in a Docker container, exposing local ports to the running Docker container.

  • Confirm that you can communicate with the containerized application.

Prerequisites

The steps on this page and the next pages were tested using the Docker Community Edition of Docker for Windows and Docker for Mac from store.docker.com. Other Docker client solutions may work, but are explicitly not supported.

Docker for Windows requires 64-bit Windows 10 Pro or Enterprise with Microsoft Hyper-V available and enabled. The version of Windows 10 must be 1607 Anniversary Update (build 14393) or later. If you are running Windows 7 or an earlier version of Windows 10, the Docker Store redirects you to instead use an earlier product named Docker Toolbox. StreamBase 10 requires Docker for Windows, and does not interact with Docker Toolbox.

Note that installing Hyper-V disables VMware Workstation or Oracle VirtualBox on the same Windows computer, because Windows 10 allows only one virtualization hypervisor to run at the same time.

Note

The virtual network interfaces configured by some hypervisor products, including Hyper-V, could conflict with earlier StreamBase 10 releases. See this troubleshooting page if you are using a StreamBase 10 release before 10.3.0.

Load and Build a Fragment Project

  1. From StreamBase Studio, select File>Load StreamBase Sample.

    In the Load Sample Projects dialog, type first in the search field. Select the Getting Started Guide search result, then click OK to load the project.

    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 the project folders in the Project Explorer view.

  2. Create an EventFlow fragment archive for the firstapp fragment:

    • In the Project Explorer view, select the sample_firstapp project folder.

    • Right-click and select Run As>Maven Install from the context menu.

    • Look for the BUILD SUCCESS message in the Console view.

      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESS
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 25.904 s
      [INFO] Finished at: 2018-06-12T12:27:33-04:00
      [INFO] Final Memory: 40M/647M
      [INFO] ------------------------------------------------------------------------

Create a StreamBase Application Project

The steps in this section create a StreamBase Application project that will build the Docker image.

  1. Optional. Open the firstapp project's /src/main/eventflow folder to determine the Group ID used by the project, which is com.tibco.sb.sample.

  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 and click Next. (If you click Finish in error, start over.)

  5. 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 a StreamBase 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.

    Click Next.

  6. 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 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 the TrustedHosts section of this application's security.conf file to allow all StreamBase Runtime node to participate in the same domain as the Docker containers. This allows node-to-node communication to occur without user authentication for nodes in the same Docker network. Members of this domain are to be trusted hosts for each other.

    To take advantage of this feature, use the --network, --hostname, and other options in your docker run command, as described in

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

  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 (because your local Maven repository has artifacts from previous StreamBase releases), select the top 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 the Docker Image

Build the Docker image as follows:

  1. Make sure your development machine is connected to the Internet.

  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 Run As>Maven Build...

    (Be sure to select the Build... option with periods.)

  4. In the Edit Configuration dialog:

    • In the Goals field, enter clean install

    • Select the Skip Tests check box.

    • Click Apply, then click Run.

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

  6. 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 either the docker images or docker image ls command:

    REPOSITORY        TAG       IMAGE ID       CREATED             SIZE
    sample/docker_1st latest    afc1258b7098   About a minute ago  691MB
    sbrt-base         10.4.0    d4dc8ddc81af   2 hours ago         691MB
    centos            7         49f7960eb7e4   7 days ago          200MB

Run Your App in a Docker Container

The steps in this section take you through creating a Docker container, running it, and exposing local machine ports to the running Docker container.

  1. Confirm the images that are available to run with the docker images or docker image ls command described in the previous section.

    Look for the image you just built: sample/docker_1st. You will use the string sample/docker_1st to add to the end of the command in the next step. Notice that the string uses a forward slash, even on Windows.

    Note

    Step 11 in the previous section shows sample/docker_1st as the image name, but the sample portion of this path may be different for you, depending on the Group ID you specified when creating your StreamBase Application project. In an earlier step, we suggested using com.tibco.sb.sample. Docker uses the last portion of this Group ID as the folder name. If you used a different Group ID, the path will match accordingly. Use the image name shown in the output of your own docker images command.

  2. Run a command like the following to name the Docker container, start it, and to map local machine ports 2000 and 10000 to the Docker container's ports with the same numbers.

    docker run -d --name firstapp -e NODENAME=A.cluster -p 2000:2000 -p 10000:10000 sample/docker_1st

    Note

    The two -p options map your host computer's ports 2000 and 10000 to the same ports on the node to be run in Docker. See Configuring Docker Images and Networks to understand why these ports are chosen and how to change them.

    You must set the NODENAME environment variable for the Docker image with the -e or --env option, as shown. You can specify the node and cluster names you prefer, as long as you specify the same cluster name for Docker-hosted images that will run together as a cluster.

    Look for output similar to this:

    d26c729222632a69b587a910f4386e5b4e71b6bf74947b0db771f139f1a8b340

    Note

    The --name firstapp argument names the Docker container as firstapp. Think of this as a shortcut name or an alias. You can instead use any name you prefer.

    Tip

    If your container name is in use, you will see an already in use message. To remove a leftover container, run docker stop containerName followed by docker rm containerName — or just use a different name in your docker run command.

  3. Confirm that your Docker container is loaded by using the docker ps or docker container ls command.

  4. Confirm that the Docker container is up and running the firstapp sample by using the following command:

    docker logs firstapp

    Look for results like the following:

    [A.cluster]  Installing node
    [A.cluster]          PRODUCTION executables
    [A.cluster]          File shared memory
    ...
    ...
    [A.cluster]          Administration port is 2000
    [A.cluster]          Discovery Service running on port 54321
    [A.cluster]          Service name is A.cluster
    [A.cluster]  Node started
    COMMAND FINISHED
  5. Confirm that you can connect to the StreamBase node running in the Docker container with commands like the following:

    docker exec firstapp epadmin display services servicetype=node

    This returns the name of the node in the containerized app:

    Service Name = A.cluster
    Service Type = node
    Network Address = dtm-adm://96b621f6a71d:2000

    Use this node name as the service name in two more commands:

    docker exec firstapp epadmin servicename=A.cluster display node
    docker exec firstapp epadmin servicename=A.cluster display engine

    Notice that the locations of resources returned by these commands are Linux paths not available on your Windows or Mac host:

    [A.cluster] Node Name = A.cluster
    [A.cluster] Node Description = No description
    [A.cluster] Node State = Started
    [A.cluster] Host Name = 96b621f6a71d
    [A.cluster] Administration Port = 2000
    [A.cluster] Discovery Service = running on port 54321
    [A.cluster] Container = tibco/sb
    [A.cluster] Node Directory = /var/opt/tibco/A.cluster
    [A.cluster] Deployment Directories = /var/opt/tibco/A.cluster/deploy
    ...

Next Steps

Next, try connecting to your Docker-hosted StreamBase Application to send and receive data:

Note

You can configure your Docker container to redirect logging from your Docker-hosted StreamBase application to the Docker host by configuring a Logback console appender in your StreamBase application. See Docker container logging for instructions on this option.