IBM Streams 4.2

Creating an IBM Streams basic domain and instance

You can create a basic domain and instance by using the IBM® Streams graphical user interfaces or the streamtool command-line interface.

A basic domain is typically used for test or development environments. Use an enterprise domain for a production environment.

Before you begin

Ensure that the value of the STREAMS_ZKCONNECT environment variable is unset. This environment variable is used to set the connection string for an external ZooKeeper server. If the value of this environment variable is not unset, IBM Streams streamtool commands might not use embedded ZooKeeper, which can cause incorrect results.
If your home directory is on a shared file system, you can only use embedded ZooKeeper on one resource at a time. IBM Streams starts embedded ZooKeeper when you start the domain. For example, if user1 starts the domain on resource A and the same user tries to start the same domain on resource B, an error occurs.
The streams.zookeeper.quorum bootstrap property indicates the host name of the embedded ZooKeeper server. Only a local host name is supported. When streamtool is first started, this property is populated with a local host name and persisted in the home directory of the user. If your home directory is on a shared file system and you want to start embedded ZooKeeper on a different resource, update the streams.zookeeper.quorum property with the new host name by using the streamtool setbootproperty command. Otherwise, an error message similar to the following example is issued: CDISA5252E Invalid value for bootstrap property 'streams.zookeeper.quorum'. For embedded ZooKeeper the value must specify the hostname for the local host. Found: host1. Use 'streamtool setbootproperty' to update the property value.

Procedure

Use this procedure to create a basic domain and instance by using the IBM Streams graphical user interfaces.
Attention: To use the IBM Streams graphical user interfaces, you must have an X Window System installed. An alternative is to use the streamtool command-line interface procedure.

You create a basic domain by using the Domain Manager. After creating the domain, you create an instance by using the Streams Console. You can open the Streams Console in the Domain Manager.
To open the Domain Manager, you can use the DomainManager.sh script or the streamtool launch command.
- To use the DomainManager.sh script, enter the following command:
```
  product-installation-root-directory/4.2.0.0/DomainManager.sh 
```
- To use the streamtool launch command, enter the following commands:
```
  source product-installation-root-directory/4.2.0.0/bin/streamsprofile.sh
  streamtool launch --domainmgr
```
Use this procedure to create a basic domain and instance by using the IBM Streams streamtool command-line interface.
1. To configure your local shell environment for IBM Streams, enter the following command:
```
  source product-installation-root-directory/4.2.0.0/bin/streamsprofile.sh
```
2. To complete this procedure in the interactive streamtool interface, enter the following command:
```
    streamtool  
```
  Notes:
  - When prompted, press Enter to use embedded ZooKeeper.
  - Using the interactive streamtool interface saves you time. IBM Streams caches some command options and information so that you do not have to reenter them. Also, you do not have to specify streamtool before each command. To exit the interactive streamtool interface, enter exit or quit.
3. To create a basic domain, enter the following command:
```
  mkdomain -d domain-id 
```
  For example:
```
  mkdomain -d StreamsDomain
```
4. To create public and private keys for IBM Streams, enter the following command:
```
  genkey
```
  Generating public and private keys eliminates the need for you to enter a password when you perform IBM Streams tasks that require authentication.
  The streamtool genkey command generates the following files:
  - Private key: user-id_priv.pem
  - Public key: user-id.pem
  IBM Streams stores the private key in the user-home-directory/.streams/key/domain-id directory. The public key is stored in ZooKeeper.
5. To start the domain, enter the following command:
```
  startdomain
```
  Tip: If the domain fails to start because a port is in use, you can change the port number by using the streamtool setdomainproperty command. For example, if the domain fails to start because the management API service and web management service ports are in use, you can enter the following command. If you specify a value of 0 for the port number, IBM Streams selects an available port.
```
setdomainproperty jmx.port=0 sws.port=0
```
  Dynamic port allocation is not ideal, however, if you have applications that use the REST API or JMX API or use tools (such as Streams Studio or Streams Console) that access those services.
6. Create one or more instances for running streams processing applications. To create an instance, enter the following command:
```
  mkinstance -i instance-id 
```
  For example:
```
  mkinstance -i StreamsInstance
```
7. Start the instance by entering the following command:
```
  startinstance 
```
8. To manage and monitor the domain, you can use the Streams Console. The domain must be started to use the console.
  To open the console:
  1. Enter geturl to display the URL for the console. For example, if your resource is myhost.mydomain.com and the port number for the console is 8440, this command displays the following URL:
```
  https://myhost.mydomain.com:8440/streams/domain/console
```
  2. Paste this URL into your browser.
9. To exit the interactive streamtool interface, enter exit or quit.