Installing StreamBase on macOS

< Previous		Next >

Before You Install

This page describes the installation of the TIBCO StreamBase® and TIBCO® Live Datamart base kit on Apple macOS platforms. The base kit for macOS includes the StreamBase Studio authoring environment, StreamBase Server, support files for the StreamBase Client API, TIBCO LiveView Server, and the LiveView extensions for StreamBase Studio.

TIBCO LiveView™ Desktop and the companion Desktop Workspace Manager are installed with a separate procedure, described in Installing LiveView Desktop.

Before you install TIBCO StreamBase, use the following checklist to make sure each target machine matches the prerequisites.

	Read through the New and Noteworthy page for the current release to look for any late-breaking information about installing StreamBase on macOS.
	If you have used StreamBase Studio on the target machine, back up your existing Studio workspace and configuration, as described below.
	Confirm that the target machine is running a supported version of macOS with the latest updates. See Supported Configurations.
	Confirm that the target machine's RAM and disk space requirements meet or exceed the minimums listed on Supported Configurations.
	Depending on where you decide to install StreamBase, you may need administrator and/or sudo rights on the target machine.
	If you are running macOS 10.12 Sierra and you are having trouble getting StreamBase Studio to start from its application bundle, see Starting StreamBase Studio on macOS 10.12 Sierra.

Limitations and Differences

TIBCO StreamBase Studio™ is provided on macOS as a client application to allow users to develop, debug, and test StreamBase modules. StreamBase installations on macOS do include a local copy of of StreamBase Server for running and testing your applications locally, on the same Mac computer as Studio.

However, StreamBase Server is explicitly not supported for build or production deployment purposes on Apple Mac machines.

Expect the following important differences when working with StreamBase Studio on macOS compared to Studio on Windows:

TIBCO strongly recommends using a two- or three-button mouse with StreamBase Studio on macOS. MacOS has strong support for two- and three-button mice based on its UNIX heritage.

In many places, StreamBase documentation directs you to right-click to open the context menu. If you are using a two-button or three-button mouse on macOS, a right-click is invoked with right mouse button as on other platforms (or with the left mouse button if you have configured for left handed use). If you are using a trackpad, use a light two-finger tap to invoke the context menu (depending on Trackpad Preference settings), or use Control+click.
StreamBase Studio supports macOS's full screen feature.
There is no Insert key on Mac keyboards, but StreamBase Studio on Windows and Linux uses Insert to add a new row in schema editor grids in Properties views and configuration editors. On macOS, use the backslash key ( \ ) for this purpose. The backslash key retains its standard meaning in other contexts, including when composing an expression in a field of the schema editor grid.
Add-on products such as the High-Performance FIX Engine install as overlays into the same location as the base StreamBase kit. These packages are distributed as .archive-bin packages. On macOS, after downloading use chmod +x to be sure you can run the installer. See below for more.
StreamBase Studio keyboard shortcuts are not always documented for Mac keyboards. In general, commands documented as Ctrl+key for Windows are accomplished with Command+key on macOS.
On macOS, commands on the main StreamBase Studio menu and on context menus throughout Studio show the keyboard equivalent of commands using Mac keyboard symbols and semantics.
In StreamBase Studio, Command+Shift+L shows a pop-up help window of all commands and their keyboard equivalents just as Ctrl+Shift+L does on Windows.
StreamBase-specific EventFlow Editor keyboard shortcuts for Insert menu commands (such as O M to place a Map operator on the canvas) all work the same on macOS as on Windows.
Some menu items are in different places in keeping with macOS standards. In particular, when StreamBase documentation directs you to open Window → Preferences, on macOS open StreamBase Studio → Preferences, or use the macOS-specific keyboard equivalent Command+comma.
StreamBase Studio Help opens in your system default web browser instead of opening in a separate application window as on Windows. The Help system in your browser is in Eclipse Help format with a left-side navigation panel and full search capabilities.
When you click a Show in Help link in the Properties view's Expression Quickref tab, a new browser tab opens for each click, instead of reusing an already-open Help tab as on Windows.

Back Up Existing StreamBase Workspace

If you used a previous release of StreamBase Studio on the target machine, create backup copies of your existing Studio workspace directories, before using StreamBase Studio in the current release. Save the backup copy with filenames that indicate the version number of the release you are archiving. For example, save SB-workspace-7-6-04.zip.

The default location of the StreamBase Studio workspace directory is described in Default Installation Directories. You may have specified a different directory the first time you ran StreamBase Studio.

Steps to Install StreamBase on macOS

TIBCO provides a StreamBase installer in standard Apple DMG (disk image) format. This installer includes a Java JDK for the exclusive use by TIBCO StreamBase software.

As downloaded from the TIBCO distribution site, the StreamBase DMG installer is delivered in a single file named according to the following pattern:

TIB_sb-cep_n.m.x_macosx_x86_64.dmg

where n.m.x is the release number. The macOS version is available for x86 64-bit only.

To install TIBCO StreamBase and TIBCO Live Datamart, follow these steps:

Double-click to open the downloaded DMG file.

Click Agree to accept the StreamBase license. This opens the DMG folder on your desktop containing subfolders like the ones shown here:

TIBCO StreamBase `n.m.x`	The TIBCO StreamBase installation folder, where `n.m.x` is the current release number in `major.minor.servicepack` format. The inclusion of the full release number allows you to have more than one StreamBase release on your Mac at the same time (but using only one at a time). See Switching for details.
doc	Full documentation for this StreamBase and Live Datamart release in HTML format. This is a copy of the `/doc` folder that will be placed in your target installation folder. You can copy this folder to a public location to make StreamBase documentation available to other users.

As with all macOS program files, you are free to install StreamBase in any standard or personal location, as long as you have write access to the folder of choice. Decide on an installation location based on the following points:
- TIBCO recommends dragging the TIBCO StreamBase n.m.x folder to a folder named Applications in your home directory. Create the $HOME/Applications folder if it does not exist. This location is presumed, and is shown in examples on this page and throughout the StreamBase documentation. The advantages of this location are:
  - The contents of home directory Applications folders are automatically included in macOS searches for application bundles
  - You automatically have write rights for any folder in your home directory, and can therefore install StreamBase add-on products with ease.
- The standard location for macOS application files is /Applications at the root of the primary disk. This location has the advantage of being standard, but the disadvantage of requiring administrator access, both to install files initially, and to install other files to the same location later. These permissions issues can complicate the installation of StreamBase add-ons.
- TIBCO's standard installation location on Linux is /opt/tibco. The default installation location for the add-ons that use an installer in the .archive.bin format install by default into /opt/tibco/sb-cep/n.m. You can choose to drag the TIBCO StreamBase folder to /opt/tibco to keep all your TIBCO products in the same location. However, the /opt folder does not exist by default on macOS machines, and rarely has write rights for all users by default.
Drag the entire TIBCO StreamBase n.m.x folder from the open DMG to the location you elected in the previous step. You may be prompted to enter an administrative password.
To close the DMG folder, right-click or Control-click anywhere in its blank space to invoke the context menu, and select Eject.

Starting StreamBase Studio on macOS 10.12 Sierra

MacOS release 10.12 Sierra has a new security model that is stricter than previous releases. As part of its new security, Sierra automatically blocks downloaded but unsigned application bundles with .app extension from being able to run. Unfortunately, this affects the application bundles for StreamBase Studio 10.x and StreamBase Manager 10.x.

You can work around these limitations in one of several ways. Choose ONE of the following options:

EITHER:

MacOS automatically flags downloaded application bundles that are unsigned with a quarantine attribute. Removing this attribute allows you to double-click to run application bundles normally. Use commands like the following:

cd <StreamBase installation location>
## Display the current attributes with the xattr command:
xattr "StreamBase Studio 7.7.app"
## This command returns entries like the following:
com.apple.FinderInfo
com.apple.quarantine
## Remove the quarantine attribute from the Studio app bundle:
sudo xattr -r -d com.apple.quarantine StreamBase\ Studio\ 7.7.app
## Remove the quarantine attribute from the Manager app bundle:
sudo xattr -r -d com.apple.quarantine StreamBase\ Manager\ 7.7.app

OR

You can always start Studio from a Terminal shell prompt by typing:
```
sbstudio &
```
(This presumes that you have configured your Terminal shell environment as described in Post-Installation Shell Configuration below.)

OR

You can start Studio by navigating into the application bundle:
- In a Finder window, navigate to your StreamBase installation folder.
- Right-click StreamBase Studio 7.x.app, and select Show Package Contents.
- Navigate to Contents → MacOS.
- Double-click sbstudio. (Do NOT run _sbstudio.)

OR

Restore the pre-Sierra security model to your macOS instance. Doing this restores the Anywhere option for the Allow apps downloaded from section of the Security and Privacy control panel. This method is not recommended because it opens your Mac to safety issues from downloaded apps and utilities from other vendors.

To do this, run the following command:
```
sudo spctl --master-disable
```
If you have tried to run Studio by double-clicking its app bundle icon, then you must still remove its quarantine flag as described above.

To reverse this setting and return to the as-shipped Sierra security model, run:
```
sudo spctl --master-enable
```

Post-Installation Shell Configuration

For all users who will run or develop with StreamBase on this Mac, you must configure their shell initialization files such as .bash_profile. The steps in this section show syntax for the Bash shell, which is the default Terminal shell on macOS. Adjust these steps if you are using another shell.

You can make the necessary environment settings by using the sb-config command, as shown in the following steps:

Modify the shell environment of all users who will run or develop with StreamBase on this Mac by adding the following command to their shell startup files. The command is shown for the recommended installation location, using the standard tilde notation to mean home directory. Adjust the path to the StreamBase installation folder if you chose another installation location.

Notice that this command uses the back quote character ( ` ), not the single quote character:
```
$ eval `~/Applications/TIBCO StreamBase n.m.x/bin/sb-config --env`
```
This command sets or adds StreamBase-specific environment variable and PATH settings to the current shell instance.
To make sure this command is executed automatically for every Terminal window opened, add commands like the following to the shell initialization file for each user.
```
if [ -d ~/Applications/TIBCO\ StreamBase\ n.m.x/bin ] ; then
    eval `~/Applications/TIBCO\ StreamBase\ n.m.x/bin/sb-config --env`
else
    echo "No StreamBase environment detected."
fi
```
You might find it helpful to create a symbolic link in your ~/Applications folder to avoid issues with the spaces in the StreamBase folder name. For example:
```
cd ~/Applications
ln -s TIBCO\ StreamBase\ 7.7.0 streambase
```
With this symlink in place, you can use the following script in your shell initialization files instead:
```
if [ -d ~/Applications/streambase/bin ] ; then
    eval `~/Applications/streambase/bin/sb-config --env`
else
    echo "No StreamBase environment detected."
fi
```

The set of items that sb-config --env configures for you is the following:

STREAMBASE_HOME environment variable

The full path to the root of the StreamBase installation directory, such as /Users/sbuser/Applications/TIBCO StreamBase 7.7.0

TIBCO_EP_HOME environment variable

Set to the same full path as STREAMBASE_HOME. This variable is required by the epadmin command-line deployment tool.

DYLD_LIBRARY_PATH environment variable

Prepends $STREAMBASE_HOME/lib to the DYLD_LIBRARY_PATH variable.

Add two StreamBase folders to the PATH

Both of the following folders must by on the shell's PATH in order to run StreamBase command-line utilities and the deployment tool:

$STREAMBASE_HOME/bin

SSTREAMBASE_HOME/distrib/tibco/bin

Add StreamBase man pages to the MANPATH

You can optionally add the folder containing man pages for StreamBase command-line utilities to the MANPATH:

$STREAMBASE_HOME/man

Installing Additional Features

For macOS, all add-on products and external adapters install as overlays into the base StreamBase folder. The installers for these add-ons are distributed as executable .archive-bin packages, which are standard .tar.gz files packaged in a shell wrapper.

These installers for macOS have file names that match the following patterns:

Adapters: TIB_sb-ad-name_version_macosx_64.archive-bin
Add-ons: TIB_sb-addin-name_version_macosx_x86_64.archive-bin

where version is the current release number in major.minor.servicepack format.

Note

The Safari browser on macOS automatically renames downloaded .archive-bin files as a safety precaution, because it detects that these files are unrecognized shell scripts. Safari adds the .txt extension so that these files are initially treated as text files.

When the download is complete, you must manually rename these files to remove the .txt extension.

After downloading one of these files, first make it executable with the chmod command. For example, for the TIBCO StreamBase Adapter for Apache Flume:

chmod +x TIB_sb-ad-flume_n.m.x_macosx_x86_64.archive-bin

For archive-bin packages, run the shell wrapper command. If you are installing into a StreamBase folder for which you do not have write privileges, run the command as root or with sudo:

cd /path/to/TIB_sb-ad-flume_n.m.x_macosx_x86_64.archive-bin
./TIB_sb-ad-flume_n.m.x_macosx_x86_64.archive-bin

The wrapper script displays a license file for you to agree to, then prompts for the full path to your base StreamBase installation. Provide the full absolute path; you do not need to escape the spaces in the folder name. For example, enter:

/Users/sbuser/Applications/TIBCO StreamBase 7.7.0

The script then unarchives its files into the STREAMBASE_HOME location you identified.

How to Start StreamBase Applications

On macOS, a StreamBase installation provides two GUI applications plus the command-line utilities listed in the StreamBase Command Reference. Man pages are provided at the shell prompt for the command-line utilities.

The two GUI applications are named as follows on the macOS file system:

sbstudio.app
sbmanager.app

Double-click to start either of these .app bundles like any other Mac app.

Note

If you are running macOS Sierra, and double-clicking does not start the application, see Starting StreamBase Studio on macOS 10.12 Sierra.

Switching Between StreamBase Releases

Because the name of the TIBCO StreamBase installation folder in ~/Applications or /Applications includes the release number, you can have more than one copy of StreamBase on your disk at the same time, and can switch back and forth between them to use one at a time.

The easiest way to do this is to use a symbolic link pointing to the actual StreamBase installation folder, and to place the path to the symbolic link's bin directory in the PATH, as recommended in Post-Installation Shell Configuration, above.

This way, when you have two or more StreamBase installations, you can quickly switch between them by re-creating the symbolic link to point to the desired version.

Uninstalling StreamBase on macOS

To uninstall StreamBase on macOS, just move the ~/Applications/TIBCO StreamBase n.m.x folder to the Trash, and remove any symbolic link you created. Your project files in your StreamBase Studio workspace are preserved when you remove the StreamBase application files.

Downgrading StreamBase Releases

When you upgrade from one StreamBase release to a new major release, on first run, StreamBase Studio automatically and silently upgrades the XML representation of your application files.

If you need to downgrade back to a previously used StreamBase release (such as to add a feature to an existing application), the older StreamBase Studio may not recognize some of the changes made to your applications by the newer Studio.

Thus, if you anticipate returning to an older StreamBase release, specify a separate workspace, and either start over with new projects in your new StreamBase Studio release, or restore your matching version-specific backup copies to the separate workspace. See above for instructions for backing up workspaces.