Customizing the Streams application image

Your IBM Streams application might require dependencies, such as software packages or libraries, that are not included in the default application image that Streams provides. To enable your application to run, you must create a custom application image based on the default application image that is provided by Streams.

Before you begin

Ensure that the following tasks have been completed:

Install the Streams service. The default application image for the service is published to the image registry when the Streams service is installed or upgraded. For more information, see Installing Streams or Upgrading Streams.
Set up an image build system with Docker installed. You must be able to access and log in to the image registry where the Streams images are located.
The custom application image must be built from the Streams default application image, which is streams-application-el7. The image registry and image tag for the default application image for your environment must be specified in the Dockerfile. Ask your administrator about the image registry and image tag to use.

About this task

The default application image contains the runtime code that is needed to run a Streams application and the streamtool commands that are required by some specialized toolkits.

Important: If you use a custom application image, then you must also create an application resource template where you specify the name of the custom application image.

The application image sets up the streamsapp operating system user for running applications. (The UID of 1000320901 is reserved for this user.) If you want applications that use this image to be run under a different user UID, you must create a user in the custom application image with a UID of 1000360000 - 1000361000, and create the user's home directory. In addition, you must specify the user information in the custom application resource template. For example, for a user with a UID of 1000360000:

SecurityContext: 
  runAsUser:  1000360000
  runAsGroup: 1000360000

Procedure

Tip: The IBMStreams/streams-resource-templates repository contains sample configuration maps and associated files for several scenarios that you can use to get started.

Create a Dockerfile file with your image-specific information.
Notes:
- The user that is specified in the Dockerfile file (that is, specified by the USER command) must either be streamsapp or a custom user. You cannot specify the root user. The resource templates repository contains a sample called CustomImageNewUser, which includes a Dockerfile file and associated configuration map that you can use to customize your application image and resource template for a custom user.
- The default working directory is set as follows:
```
WORKDIR "/home/${USER}"
```
Create the application image, assign a new image tag to it, and push it to your image registry.
1. If necessary, log in to the image registry. The following commands assume that you have navigated to the directory where the Dockerfile file is located. Alternatively, you can use the -f flag to indicate the location of the Dockerfile file.
2. Create the application image:
```
docker build options
```
  For example:
```
docker build ./ -t streams-custom-application-el7:5.5.0.0 --pull
```
3. Assign an image tag to the application image:
```
docker tag options
```
  For example:
```
docker tag streams-custom-application-el7:5.5.0.0 myregistry.default.svc:5000/myProject/streams-custom-application-el7:5.5.0.0
```
4. Push the application image to the image registry where your Streams images are located:
```
docker push options
```
  For example:
```
docker push myregistry.default.svc:5000/myProject/streams-custom-application-el7:5.5.0.0
```
For more information about these commands and options, see the Dockerfile reference documentation.

What to do next

You must update your custom application resource template to specify your custom application image. For example:

image: myregistry.default.svc:5000/myProject/streams-custom-application-el7:5.5.0.0

If your image registry requires a Docker pull secret, you must specify it in the template. For more information, see Using image pull secrets. If you haven't created an application resource template yet, see Creating a Streams application resource template.

After you set up a custom image and make the associated changes to the custom application resource template configuration map, you must provision a Streams instance that uses the configuration map. If the Streams instance is already provisioned, you must edit it and specify the name of the configuration map.

After the application resource template is created, you can configure submission-time parameters to optimize job deployment to use one or more application resource templates. For more information, see Configuring submission-time parameters to optimize job deployment.