Creating New Applications | Developer Guide

Overview
Using the CLI
Using the Web Console

Overview

You can create a new OpenShift application using the web console or by running the oc new-app command from the CLI. OpenShift creates a new application by specifying source code, images, or templates. The new-app command looks for images on the local Docker installation (if available), in a Docker registry, or an OpenShift image stream.

If you specify source code, new-app attempts to construct a build configuration that builds your source into a new application image. It also constructs a deployment configuration that deploys that new image, and a service to provide load balanced access to the deployment that is running your image.

If you specify source code, you may need to run a build with oc start-build after the application is created.

Using the CLI

You can create a new application using the oc new-app command from the CLI.

Specifying Source Code

The new-app command allows you to create applications using source code from a local or remote Git repository. If only a source repository is specified, new-app tries to automatically determine the type of build strategy to use (Docker or Source), and in the case of Source type builds, an appropriate language builder image.

You can tell new-app to use a subdirectory of your source code repository by specifying a --context-dir flag. Also, when specifying a remote URL, you can specify a Git reference to use by appending #[reference] to the end of the URL.

If using a local Git repository, the repository must have an origin remote that points to a URL accessible by the OpenShift cluster.

Example 1. To Create an Application Using the Git Repository at the Current Directory:

$ oc new-app .

Example 2. To Create an Application Using a Remote Git Repository and a Context Subdirectory:

$ oc new-app https://github.com/openshift/sti-ruby.git \
    --context-dir=2.0/test/puma-test-app

Example 3. To Create an Application Using a Remote Git Repository with a Specific Branch Reference:

$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4

Build Strategy Detection

If new-app finds a Dockerfile in the repository, it generates a Docker build strategy. Otherwise, it generates a Source strategy. To use a specific strategy, set the --strategy flag to either source or docker.

Example 4. To Force new-app to Use the Docker Strategy for a Local Source Repository:

$ oc new-app /home/user/code/myapp --strategy=docker

Language Detection

If creating a Source build, new-app attempts to determine which language builder to use based on the presence of certain files in the root of the repository:

Table 1. Languages Detected by `new-app`
Language	Files
`ruby`	*Rakefile, Gemfile, config.ru*
`jee`	*pom.xml*
`nodejs`	*app.json, package.json*
`php`	*index.php, composer.json*
`python`	*requirements.txt, config.py*
`perl`	*index.pl, cpanfile*

After a language is detected, new-app searches the OpenShift server for image stream tags that have a supports annotation matching the detected language, or an image stream that matches the name of the detected language. If a match is not found, new-app searches the Docker Hub registry for an image that matches the detected language based on name.

To override the image that new-app uses as the builder for a particular source repository, the image (either an image stream or Docker specification) can be specified along with the repository using a ~ as a separator.

Example 5. To Use Image Stream myproject/my-ruby to Build the Source at a Remote GitHub Repository:

$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git

Example 6. To Use Docker Image openshift/ruby-20-centos7:latest to Build Source in a Local Repository:

$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app

Specifying an Image

The new-app command generates the necessary artifacts to deploy an existing image as an application. Images can come from image streams in the OpenShift server, images in a specific registry or Docker Hub, or images in the local Docker server.

The new-app command attempts to determine the type of image specified in the arguments passed to it. However, you can explicitly tell new-app whether the image is a Docker image (using the --docker-image argument) or an image stream (using the -i|--image argument).

If you specify an image from your local Docker repository, you must ensure that the same image is available to the OpenShift cluster nodes.

Example 7. To Create an Application from the DockerHub MySQL Image:

$ oc new-app mysql

To create an application using an image in a private registry, specify the full Docker image specification.

Example 8. To Create an Application from a Local Registry:

$ oc new-app myregistry:5000/example/myimage

If the registry that the image comes from is not secured with SSL, cluster administrators must ensure that the Docker daemon on the OpenShift nodes is run with the --insecure-registry flag pointing to that registry. You must also tell new-app that the image comes from an insecure registry with the --insecure-registry=true flag.

To create an application from an existing image stream, specify the namespace (optional), name, and tag (optional) for the image stream.

Example 9. To Create an Application from an Existing Image Stream with a Specific Tag:

$ oc new-app my-stream:v1

Specifying a Template

The new-app command can instantiate a template from a previously stored template or from a template file. To instantiate a previously stored template, specify the name of the template as an argument. For example, store a sample application template and use it to create an application.

Example 10. To Create an Application from a Previously Stored Template:

$ oc create -f examples/sample-app/application-template-stibuild.json
$ oc new-app ruby-helloworld-sample

To use a template in the file system directly, without first storing it in OpenShift, use the -f|--file argument or simply specify the file name as the argument to new-app.

Example 11. To Create an Application from a Template in a File:

$ oc new-app -f examples/sample-app/application-template-stibuild.json

Template Parameters

When creating an application based on a template, use the -p|--param argument to set parameter values defined by the template.

Example 12. To Specify Template Parameters with a Template:

$ oc new-app ruby-helloworld-sample \
    -p ADMIN_USERNAME=admin,ADMIN_PASSWORD=mypassword

Specifying Environment Variables

When generating applications from source or an image, you can use the -e|--env argument to specify environment to be passed to the application container at run time.

Example 13. To Set Environment Variables When Creating an Application for a Database Image:

$ oc new-app openshift/postgresql-92-centos7 \
    -e POSTGRESQL_USER=user \
    -e POSTGRESQL_DATABASE=db \
    -e POSTGRESQL_PASSWORD=password

Specifying Labels

When generating applications from source, images, or templates, you can use the l|--label argument to add labels to objects created by new-app. This is recommended, as labels make it easy to collectively select, manipulate, and delete objects associated with the application.

Example 14. To Use the Label Argument to Label Objects Created by new-app:

$ oc new-app https://github.com/openshift/ruby-hello-world -l name=hello-world

Command Output

The new-app command generates OpenShift objects that will build, deploy, and run the application being created. Normally, these objects are created in the current project using names derived from the input source repositories or the input images. However, new-app allows you to modify this behavior.

Output Without Creation

To see a dry-run of what new-app will create, you can use the -o|--output flag with a value of either yaml or json. You can then use the output to preview the objects that will be created, or redirect it to a file that you can edit and then use with oc create to create the OpenShift objects.

Example 15. To Output new-app Artifacts to a File, Edit Them, Then Create Them Using oc create:

$ oc new-app https://github.com/openshift/ruby-hello-world -o json > myapp.json
$ vi myapp.json
$ oc create -f myapp.json

Object names

Objects created by new-app are normally named after the source repository or the image used to generate them. You can set the name of the objects produced by adding a --name flag to the command.

Example 16. To Create new-app Artifacts with a Different Name:

$ oc new-app https://github.com/openshift/ruby-hello-world --name=myapp

Object Project or Namespace

Normally new-app creates objects in the current project. However, you can tell it to create objects in a different project that you have access to using the -n|--namespace argument.

Example 17. To Create new-app Artifacts in a Different Project:

$ oc new-app https://github.com/openshift/ruby-hello-world -n myproject

Artifacts Created

The set of artifacts created by new-app depends on the artifacts passed as input: source repositories, images, or templates.

Table 2. `new-app` Output Objects
Artifact	Description
`BuildConfig`	A `BuildConfig` is created for each source repository specified in the command line. The `BuildConfig` specifies the strategy to use, the source location, and the build output location.
`ImageStreams`	For `BuildConfig`, two `ImageStreams` are usually created: one to represent the input image (the builder image in the case of `Source` builds or FROM image in case of `Docker` builds), and another one to represent the output image. If a Docker image was specified as input to `new-app`, then an image stream is created for that image as well.
`DeploymentConfig`	A `DeploymentConfig` is created either to deploy the output of a build, or a specified image. The `new-app` command creates EmptyDir volumes for all Docker volumes that are specified in containers included in the resulting `DeploymentConfig`.
`Service`	The `new-app` command attempts to detect exposed ports in input images. It uses the lowest numeric exposed port to generate a service that exposes that port. In order to expose a different port, after `new-app` has completed, simply use the `oc expose` command to generate additional services.
Other	Other objects can be generated when instantiating templates.

Advanced: Multiple Components and Grouping

The new-app command allows creating multiple applications from source, images, or templates at once. To do this, simply specify multiple parameters to the new-app call. Labels specified in the command line apply to all objects created by the single call. Environment variables apply to all components created from source or images.

Example 18. To Create an Application from a Source Repository and a Docker Hub Image:

$ oc new-app https://github.com/openshift/ruby-hello-world mysql

If a source code repository and a builder image are specified as separate arguments, new-app uses the builder image as the builder for the source code repository. If this is not the intent, simply specify a specific builder image for the source using the ~ separator.

Grouping Images and Source in a Single Pod

The new-app command allows deploying multiple images together in a single pod. In order to specify which images to group together, use the + separator. The --group command line argument can also be used to specify which images should be grouped together. To group the image built from a source repository with other images, specify its builder image in the group.

Example 19. To Deploy Two Images in a Single Pod:

$ oc new-app nginx+mysql

Example 20. To Deploy an Image Built from Source and an External Image Together:

$ oc new-app \
    ruby~https://github.com/openshift/ruby-hello-world \
    mysql \
    --group=ruby+mysql

Using the Web Console

You can also create applications using the web console:

While in the desired project, click Add to Project:
Enter the repository URL for the application to build:

Select either a builder image from the list of images in your project, or from the global library:

Only image stream tags which have the builder tag listed in their annotations will appear in this list, as demonstrated here:

kind: "ImageStream"
apiVersion: "v1"
metadata:
  name: "ruby"
  creationTimestamp: null
spec:
  dockerImageRepository: "registry.access.redhat.com/openshift3/ruby-20-rhel7"
  tags:
    -
      name: "2.0"
      annotations:
        description: "Build and run Ruby 2.0 applications"
        iconClass: "icon-ruby"
        tags: "builder,ruby" (1)
        supports: "ruby:2.0,ruby"
        version: "2.0"

1	Including builder here ensures this `ImageStreamTag` will appear in the web console as a builder.

Modify the settings in the new application screen to configure the objects to support your application:

1	The builder image name and description.
2	The application name used for the generated OpenShift objects.
3	Routing configuration section for making this application publicly accessible.
4	Deployment configuration section for customizing deployment triggers and image environment variables.
5	Build configuration section for customizing build triggers.
6	Replica scaling section for configuring the number of running instances of the application.
7	The labels to assign to all items generated for the application. You can add and edit labels for all objects here.