epadmin Connection to Docker Images

Contents

Prerequisites
Run Docker Image with only an Admin Port
Run epadmin Using docker exec Commands
Run epadmin Locally With Authentication
Default Security for StreamBase Docker Nodes
Configure the Container's User Password
Sending Data Manually with epadmin
Sending Data with a Feed Simulation
Stop and Remove the Container

This page demonstrates connecting to a Docker containerized application from the Docker host using only an administrative port and epadmin commands to send data to and receive data from the app, both manually and with a feed simulation.

See Legacy Connection to Docker Images for the related procedures to connect to a containerized app using the traditional StreamBase URI.

Prerequisites

This page assumes:

  • You have the Docker for Windows or Docker for Mac client program installed and running on the host machine.

  • You have a Docker image available. For steps to create one from StreamBase Studio, see Creating and Running Docker Images.

See the Prerequisites section of the Creating Docker Images page for important information on the limitations and complications of the Docker for Windows product.

Run Docker Image with only an Admin Port

The Run Your App in a Docker Container section of the previous page, Creating and Running Docker Images, showed how to run a Docker image by redirecting both the StreamBase app's admin port 2000 and its EventFlow listening port 10000 to the same ports on the host machine.

The steps in this section go back through those commands, but with an important difference. We will use the same Docker image already built, but redeploy it into a new Docker container, this time redirecting only the admin port, 2000.

The advantage of this deployment method is that you can deploy multiple copies of the same EventFlow application, even if they each use the same default EventFlow listening port, 10000. You only need to deploy each container with a separately redirected admin port to be able to communicate from the Docker host to each StreamBase container individually.

  1. Open a StreamBase Command Prompt (Windows) or a StreamBase-configured Terminal (macOS).

  2. First, determine whether you have a container running. Run either:

    docker ps
docker container ls

  3. If a container with name firstapp is running the image sample/docker_1st, stop it with either of these commands: 

    docker stop firstapp
docker container stop firstapp

    Give the stop command a moment to complete. Then remove the container, using either of the following commands: 

    docker rm firstapp
docker container rm firstapp

  4. If you have not explicitly removed the Docker image you built in previous pages, then Docker still has the image ready for deployment. Confirm the available images using either the docker images or docker image ls command, and look for the image you built from the folder sample/docker_1st. 

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

    (If necessary, go back through the steps on the Creating and Running Docker Images page through the Build the Docker Image section. Then return to this step.)

  5. Run a command like the following to name the Docker container, start it, and to map local machine port 2000 to the Docker container's port with the same number. Notice that this is the same command you ran on the Creating and Running Docker Images page, except leaving out the port 10000 redirection this time. 

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

    Look for output similar to this:

    d71b3c306af433ac5700caf565cc62c7b25436239ef057319291cbe367470fa3

    As before, the --name firstapp argument names the Docker container as firstapp, which is used to address the container in the next set of commands. As before, the NODENAME variable must be set, but the node name you choose is up to your site's standards. Notice that we are only mapping host port 2000 to docker container port 2000 this time.

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

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

  8. 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://d71b3c306af4:2000

    Use this node name as the service name in subsequent commands.

Run epadmin Using docker exec Commands

You can run any command known to your Docker container as long as you know its container name. This allows you to run any StreamBase epadmin command by prefixing it with docker exec containerName. For example, use the following command to see the StreamBase Runtime environment in the container: 

docker exec firstapp epadmin display services

If you prefer, you can continue to prefix all epadmin commands with docker exec containerName. Doing so does not require authentication of your epadmin commands, because those are run by Docker in the context of the container's operating system. 

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

You can use unique abbreviations for option arguments:

docker exec firstapp epadmin --servicen=A.cluster display node
docker exec firstapp epadmin --servicen=A.cluster display engine

Run epadmin Locally With Authentication

Instead of using docker exec to connect to your StreamBase or LiveView application in a Docker container, you can run epadmin locally on your Docker host to connect to the container. This method:

  • Can have shorter commands to type, because you can leave out the docker exec containerName.

  • Requires adding authentication options to the command line, which adds back more to type.

  • Can use short abbreviations for the authentication options, reducing typing yet again.

  • Requires configuring a password for the container's configured username, described in the next section.

Default Security for StreamBase Docker Nodes

Newly created StreamBase Runtime nodes use a set of default security settings, unless overridden by explicit configuration settings. Those defaults are:

  • The application is a member of the default local authentication realm named default-realm.

  • Two security roles are defined: administrator and monitor (plus a deprecated role, switchadmin, which is a legacy alias for the administrator role).

For Docker containers generated with StreamBase Studio 10.4 or later, each container has the following security settings:

  • The default administrative user name for StreamBase and LiveView management is tibco.

  • This initial user name has a randomly generated password that cannot be determined.

  • Studio-generated Docker containers are configured with a security.conf file that grants Trusted Hosts status for all nodes in the dockerDomain you specified when creating the Studio project. (By default, dockerDomain is example.com.)

These defaults balance security with ease of use for simple node-running tasks during development. You can change most of these defaults as described in Configuring Docker Images and Networks.

Configure the Container's User Password

The containerized application runs in a virtual machine with its own IP address, different from the address and domain of the Docker host. Under these circumstances, the StreamBase Runtime requires authenticated access from the Docker host (your development machine) and nodes running in Docker containers. That is, you must provide a valid name and password for the containerized app in order to connect to its streams.

However, the random password generated for the administrative username in the container is not known and is not knowable, as a security measure. Therefore, to communicate with the containerized node from the Docker host, you must set a new password for the default username.

Do this with a command like the following:

docker exec firstapp epadmin --servicename=A.cluster change password 
  --username=tibco --password=secret

(This command is shown on two lines for clarity; enter it as a single command.)

Once you have a known password for the default username, you can run epadmin commands on your host computer to communicate with the node in the container, without using the docker exec prefix. For example: 

epadmin --adminport=2000 --username=tibco --password=secret display node

Remember that you can abbreviate parameter names as long as your abbreviations remain unique for the current epadmin target. Thus: 

epadmin --ad=2000 --us=tibco --pa=secret display node

With the abbreviated syntax, the equals signs between options and their arguments are optional:

epadmin --ad 2000 --us tibco --pa secret display node

The remaining examples on this page use this abbreviated syntax.

Sending Data Manually with epadmin

The commands in this section presume that you have configured a password for the containerized node's default username as shown in the previous section. The default username is shown as tibco throughout.

First, send manually enqueued tuples with the following steps:

  1. Open a StreamBase Command Prompt (Windows) or StreamBase-configured shell prompt (macOS). This is window 1.

  2. To verify that you are not running a StreamBase application locally on your host machine, run epadmin display services. The command returns silently if no services are running.

    (This command might return a list of services on other machines in your local subnet. In this case, run:

    epadmin display services --servicename=clustername

    where clustername is usually your system login name. See Clusters.)

  3. Connect to the StreamBase node running in the Docker container, and run the same display services command. prefixed with docker exec firstapp: 

    docker exec firstapp epadmin display services

  4. Compare the output of the two epadmin display services commands. This confirms that you are not running a StreamBase application locally but are running one in the Docker container.

  5. In window 1, set up a dequeue for the first output stream. Run:

    epadmin --ad=2000 --us=tibco --pa=secret dequeue stream --path=BigTrades

  6. Open another command window and set up a dequeue for the other output stream. This is window 2. 

    epadmin --ad=2000 --us=tibco --pa=secret dequeue stream --path=AllTheRest

    Notice that no output is produced yet. The command windows are waiting to show output from the two output streams.

  7. Set up an enqueue to the app's input stream. Open a third command window and run:

    epadmin --ad=2000 --us=tibco --pa=secret enqueue stream

  8. Send data manually. In window 3, send the following tuples:

    • IBM, 4000

    • MSFT, 5600

    • GOOG, 12000

  9. Observe the following in window 1:

    • Tuple = GOOG,12000

    And the following in window 2:

    • Tuple = IBM,4000

    • Tuple = MSFT,5600

  10. Type Ctrl+C in window 3 to stop the enqueue processes. Leave the two dequeue command windows running as-is.

Sending Data with a Feed Simulation

Next, run a feed simulation to enqueue tuples:

  1. Return to StreamBase Studio, using the same workspace used in Creating Docker Images.

  2. In your sample_firstapp project, navigate to src/main/resources and select that folder name.

  3. Right-click and select StreamBase>Open Command Prompt Here (Windows) or Open Command Terminal Here (macOS). This opens a new window 4 in the folder that contains the feed simulation files.

  4. In the new window 4, run:

    epadmin --ad=2000 --us=tibco --pa=secret start playback --sim=firstapp-enum.sbfs

  5. Data now flows to the two output ports, and therefore to the two dequeue windows. Only trades with stock quantities over 10000 go to the BigTrades port dequeued in window 1.

  6. To end the feed simulation, run:

    epadmin --ad=2000 --us=tibco --pa=secret stop playback --id=0

  7. Type Ctrl+C in windows 1 and 2 to stop the dequeue processes. Close the four windows as needed.

  8. When done, you can stop and remove the container as described in Stop and Remove the Container in the previous page.

Stop and Remove the Container

To stop the containerized application, run either:

docker stop firstapp
docker container stop firstapp

Give the stop command a moment to complete. To then remove the containerized application, run either: 

docker rm firstapp
docker container rm firstapp