Vagrant’s power for creating and distributing portable and reproducible environments derives from using a single file (Vagrantfile) to describe the target environment. A Vagrantfile defines required resources, such as virtual-machine images, networking, and provisioning steps. A separate directory containing a Vagrantfile is used for each target environment.

When a box is brought up, Vagrant automatically creates a Vagrant synchronized directory using the vagrant-sshfs plugin. This synchronized directory maps your home directory on the host into the Container Development Kit virtual machine.

For example, /home/joe/ on the host is synchronized to /home/joe/. On Microsoft Windows, the home folder, C:\Users\joe is mapped to /c/home/joe within the virtual machine.

This provides a convenient and automated method to move code, data, and configuration from the host machine to your Vagrant boxes.

A number of other methods are available for sharing folders or making copies, such as rsync, NFS, or VirtualBox shared folders. The type of synchronization used for each shared folder can be set in the definition for the shared folder in the Vagrantfile (the config.vm.synced_folder option). Shared folder definitions may also be in the Vagrantfile that comes with a Vagrant box. This is important to remember if you are trying to completely disable shared folders or change the method used for sharing data.

Run the following command from the directory in which the Vagrant box was initialized (in this example, the rhel-ose Vagrantfile was used to provision the Container Development Kit Vagrant box):

~/cdk/components/rhel/rhel-ose]$ vagrant service-manager env
Configured services:
docker - running
openshift - running
kubernetes - stopped

docker env:
# Set the following environment variables to enable access to the
# docker daemon running inside of the vagrant virtual machine:
export DOCKER_HOST=tcp://10.1.2.2:2376
export DOCKER_CERT_PATH=/home/john/down/cdk/components/rhel/rhel-ose/.vagrant/machines/default/libvirt/docker
export DOCKER_TLS_VERIFY=1
export DOCKER_API_VERSION=1.21
# run following command to configure your shell:
# eval "$(vagrant service-manager env docker)"

openshift env:
You can access the OpenShift console on: https://10.1.2.2:8443/console
To use OpenShift CLI, run: oc login https://10.1.2.2:8443

Run the following command to set the required environment variables, so that the docker client on the host system can be used to interact with the Docker service running inside the Container Development Kit virtual machine:

~]$ eval "$(vagrant service-manager env docker)"

Run the following command from the directory in which the Vagrant box was initialized (in this example, the rhel-ose Vagrantfile was used to provision the Container Development Kit Vagrant box).

~/cdk/components/rhel/rhel-ose]$ vagrant service-manager env docker
# Set the following environment variables to enable access to the
# docker daemon running inside of the vagrant virtual machine:
export DOCKER_HOST=tcp://10.1.2.5:2376
export DOCKER_CERT_PATH='C:\cygwin64\home\cdk\cdk\components\rhel\rhel-ose\.vagrant\machines\default\virtualbox\docker\'
export DOCKER_TLS_VERIFY=1
export DOCKER_API_VERSION=1.21
# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager env docker | tr -d '\r')"

openshift env:
You can access the OpenShift console on: https://10.1.2.2:8443/console
To use OpenShift CLI, run: oc login https://10.1.2.2:8443

To set the required environment variables, so that the docker.exe client on the host system can be used to interact with the Docker service running inside the Container Development Kit virtual machine, you need to run the following commands (note that you need to use the Cygwin Bash environment for the commands to work properly):

~]$ export VAGRANT_DETECTED_OS=cygwin

~]$ eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager env docker | tr -d '\r')"

Registering your Red Hat Enterprise Linux system is highly recommended. Until you register, you cannot use the official Red Hat repositories to:

Red Hat Enterprise Linux base container images are configured to have Docker use the credentials of the host system. So when you try to install packages inside of a container, the yum command uses the host credentials to gain access to those packages from Red Hat. Without a valid Red Hat subscription, you will not have a fully functioning setup for building Red Hat Enterprise Linux containers.

The process of registering your Container Development Kit virtual machine with Red Hat is automated using the vagrant-registration plugin. By default, when a Vagrant box is started, you are prompted to enter your username and password for the Red Hat Customer Portal. When the registration plugin is properly configured, the Vagrant box is automatically attached to an available subscription.

When a Red Hat Enterprise Linux VM is registered in Container Development Kit, an identity and time-limited entitlement is created for that VM. Once it is registered, the VM does not need to be re-registered until the Container Development Kit entitlement expires. Once the time limit is up, that container loses access to the Red Hat software repositories (CDN).

You can register your Container Development Kit system with a valid Red Hat Enterprise Linux Developer Subscription. Joining the Red Hat Developers program also provides a path to getting registration credentials. Once you register a Container Development Kit VM, you get a new entitlement that lasts for 90 days that does not come out of your pool. If you re-register the same VM, you will get a new 90 day entitlement. You can do this over and over.

There are a few things you should know about releasing a subscription:

It is recommended that you store your Red Hat credentials, so that you do not have to answer the prompts every time you bring up a Vagrant box. This is mandatory for complex Vagrantfiles that bring up multiple virtual machines from a single Vagrantfile.

To store your credentials, the following lines should be added to the per-user Vagrantfile. The path to that file is different for the different platforms:

The configuration will be available to all boxes started under that user ID. The per-user Vagrantfile is not created automatically.

Vagrant.configure('2') do |config|
 config.registration.username = '<your Red Hat username>'
 config.registration.password = '<your Red Hat password>'
end

Alternatively, if you prefer not to store your Red Hat credential details in the file system, you can use the following configuration to retrieve them from environment variables. Remember to store your username in the $SUB_USERNAME environment variable (SUB_USERNAME for Windows) and your password in the $SUB_PASSWORD environment variable (SUB_PASSWORD for Windows) before starting Vagrant.

Vagrant.configure('2') do |config|
  config.registration.username = ENV['SUB_USERNAME']
  config.registration.password = ENV['SUB_PASSWORD']
end

These settings may also be used in a specific Vagrantfile that will override the settings in the per-user ~/.vagrant.d/Vagrantfile. In an existing Vagrantfile, there will already be a block that begins with Vagrant.configure('2') do |config|, so just add the two config.registration lines (see above) in the existing block.

For more information, see the vagrant-registration-README.md file in the ~/cdk/plugins directory of the ZIP file containing the CDK software components.

The version of the Docker client on your host machine and the version of the Docker engine used within the Container Development Environment impose certain limitations on the way the Docker service can be used.

Install the docker package, which provides the docker executable. The package is available from the rhel-7-server-extras-rpms (Red Hat Enterprise Linux 7 Server - Extras) repository. Use the following command as root to enable the repository:

~]# subscription-manager repos --enable=rhel-7-server-extras-rpms

Install the docker package using the following command as root:

~]# yum install -y docker

If you already have the docker binary installed on your system (for example, as a part of the Docker Toolbox), check that it is the correct version (1.9.1) for use with the Docker service provided by the Container Development Kit virtual machine by running the following command:

~]$ docker version
Client:
 Version:         1.9.1

[...]

If the version of the docker binary is different from what is required for working with the Docker service provided by the Container Development Kit box, or if you do not have the docker binary installed, see the following procedure.

If you already have the docker.exe binary installed on your system (for example, as a part of the Docker Toolbox), check that it is the correct version (1.9.1) for use with the Docker service provided by the Container Development Kit virtual machine by running the following command (using the Cygwin Bash environment):

~]$ docker version
Client:
 Version:         1.9.1

[...]

If the version of the docker.exe binary is different from what is required for working with the Docker service provided by the Container Development Kit box, or if you do not have the docker.exe binary installed, see the following procedure.

Run the docker version command to see the version of both the Docker Client and Docker Server:

~]$ docker version
Client:
 Version:         1.9.1
 API version:     1.21
 Package version: docker-1.9.1-25.el7.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.9.1
 Built:
 OS/Arch:         linux/amd64

Server:
 Version:         1.9.1
 API version:     1.21
 Package version: docker-1.9.1-25.el7.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.9.1
 Built:
 OS/Arch:         linux/amd64

Run the docker info command to see information about the host system (which, in this case, is the virtualized Red Hat Enterprise Linux instance managed by Vagrant), utilization of virtualization resources, basic networking information, and the numbers of managed containerrs and images:

~]$ docker info
Containers: 14
Images: 32
Server Version: 1.9.1
Storage Driver: devicemapper
 Pool Name: VolGroup00-docker--pool
 Pool Blocksize: 524.3 kB
 Base Device Size: 107.4 GB
 Backing Filesystem: xfs
 Data file:
 Metadata file:
 Data Space Used: 2.172 GB
 Data Space Total: 13.6 GB
 Data Space Available: 11.43 GB
 Metadata Space Used: 1.016 MB
 Metadata Space Total: 46.14 MB
 Metadata Space Available: 45.12 MB
 Udev Sync Supported: true
 Deferred Removal Enabled: true
 Deferred Deletion Enabled: true
 Deferred Deleted Device Count: 0
 Library Version: 1.02.107-RHEL7 (2015-12-01)
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.10.0-327.13.1.el7.x86_64
Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo)
CPUs: 2
Total Memory: 2.781 GiB
Name: rhel-cdk
ID: PZ3X:6J7V:OF4L:KZRY:XXDT:QXCU:UHGQ:XMWE:EMM5:4POR:CG6D:YF4S

Run the docker images command to display a list of images available in the local registry.

~]$ docker images
REPOSITORY                                                 TAG       IMAGE ID      CREATED      VIRTUAL SIZE
docker.io/prom/haproxy-exporter                            latest    2b168f203700  11 days ago  23.64 MB
registry.access.redhat.com/openshift3/ose-pod              v3.1.1.6  2b96d2bcbc46  2 weeks ago  428 MB
registry.access.redhat.com/openshift3/ose-sti-builder      v3.1.1.6  983aa720a8e7  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose-deployer         v3.1.1.6  d772a87d1aac  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose                  v3.1.1.6  88178069a37f  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose-haproxy-router   v3.1.1.6  5e18f7fbcc6c  3 weeks ago  456.8 MB
registry.access.redhat.com/openshift3/ose-docker-registry  v3.1.1.6  3c272743b20a  3 weeks ago  478.5 MB

Run the docker ps command to display a list of running containers. Add the --all or -a parameter to list all available containers (not just the running ones). As you can see from the example output below, there are several running containers in Container Development Kit immediately after launch. These containers provide some of the services offered by Container Development Kit and as such should not be stopped or removed. The example below shows containers with the OpenShift service

Use the --format parameter to specify what information you want displayed about the individual containers (see the docker-ps(1) manual page for a list of available placeholders). For example:

~]$ docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  IMAGE                                               COMMAND                 STATUS
ce4817df7620  prom/haproxy-exporter:latest                        "/bin/go-run -haproxy"  Up 55 minutes
e38b37b6e13a  openshift3/ose-docker-registry:v3.1.1.6             "/bin/sh -c 'DOCKER_R"  Up 56 minutes
8abd50d2311f  openshift3/ose-pod:v3.1.1.6                         "/pod"                  Up 56 minutes
6821a60044a8  openshift3/ose-haproxy-router:v3.1.1.6              "/usr/bin/openshift-r"  Up 56 minutes
5312e060116d  openshift3/ose-pod:v3.1.1.6                         "/pod"                  Up 56 minutes
8c94cc0c049b  registry.access.redhat.com/openshift3/ose:v3.1.1.6  "/usr/bin/openshift s"  Up 59 minutes

Run the docker stats <container> command to display a live output showing resource-usage statistics for a specific running container. For example:

~]$ docker stats openshift
CONTAINER  CPU %  MEM USAGE / LIMIT    MEM %  NET I/O    BLOCK I/O
openshift  0.00%  110.4 MB / 2.986 GB  3.70%  0 B / 0 B  77.24 MB / 3.708 MB

Run the docker inspect <container> command to show low-level information about a container or an image in JSON format. Use the --type parameter to specify whether you want to display information about a container (the default) or an image in case you have containers and images of the same name.

Use the --format parameter to specify what part of the output you want displayed (see the docker-inspect(1) manual page for examples of the output). For example, define the following format to list network ports exposed by the container:

~]$ docker inspect --format='{{.Config.ExposedPorts}}' openshift
map[8443/tcp:{} 53/tcp:{}]

Run the docker search <search-term> command to search the pre-configured registries for images. For example, to search for images containing the string rhscl in the name or namespace, use the following command:

~]$ docker search rhscl
INDEX        NAME                                                           DESCRIPTION                                     STARS  OFFICIAL  AUTOMAT
docker.io    docker.io/rhscl/mongodb-26-centos7                             A Centos7 based MongoDB v2.6 image for use...   0
redhat.com   registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7  Developer toolset toolchain                     0
redhat.com   registry.access.redhat.com/rhscl/httpd-24-rhel7                Apache HTTP 2.4 Server                          0
redhat.com   registry.access.redhat.com/rhscl/mariadb-100-rhel7             MariaDB 10.0 SQL database server                0
redhat.com   registry.access.redhat.com/rhscl/mongodb-26-rhel7              MongoDB 2.6 NoSQL database server               0
redhat.com   registry.access.redhat.com/rhscl/mysql-56-rhel7                MySQL 5.6 SQL database server                   0
redhat.com   registry.access.redhat.com/rhscl/nginx-16-rhel7                Nginx 1.6 server and a reverse proxy server     0
[...]

Run the docker pull <image> command to download (pull) the specified image to your system for local use. Note that while it is possible to provide just the name of the image, it is better practice to also specify the registry you want to pull from and the namespace in which the particular image is published. The naming convention follows this order: [registry/][namespace/]name.

For example, to pull the image with the toolchain components of the Red Hat Developer Toolset from the Red Hat Atomic Registry, use the following command:

~]$ docker pull registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7
Using default tag: latest
68f6775524af: Download complete
6c3a84d798dc: Download complete
Status: Downloaded newer image for registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7:latest

~]$ docker images registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7
REPOSITORY                                                     TAG     IMAGE ID      CREATED      VIRTUAL SIZE
registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7  latest  68f6775524af  7 weeks ago  365.5 MB

Run the docker load < file.tar command to load an image from a local file file.tar. By default, the docker pull command loads image data from the standard input. To load an image from a file, use the --input or -i parameter. For example to load the Red Hat Developer Toolset toolchain image that was previously saved to a tar file using the docker save command, use the following command:

~]$ docker load -i devtoolset.tar

Run the docker run <image> <command> command to launch a new container from an image and run the specified command. Use the --name parameter to specify a name for the container to prevent the Docker service from assigning a random name to the container. For example, to run the uname -a command (and display its output) in a container created from the Red Hat Developer Toolset toolchain image, use the following command:

~]$ docker run --name devtoolset registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 uname -a
Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux

~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  NAMES       COMMAND     STATUS
22b819dec3f1  devtoolset  "uname -a"  Exited (0) 2 seconds ago
[...]

Run the docker stop <container> command to stop one or more containers. This action tries to gracefully shut down the applications running in the container by sending them the SIGTERM signal (followed by the SIGKILL signal if SIGTERM does not work). For example, to stop the container created in the previous example, use the following command:

~]$ docker stop devtoolset
devtoolset

~]$ docker ps | grep devtoolset

Use the docker start -i <container> command to run the container stopped in the previous example (the --interactive or -i parameter ensures that the container’s standard output is attached to your current shell — in other words, it ensures that the output of the command executed in the container is displayed):

~]$ docker start -i devtoolset
Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux

Run the docker run -ti <image> bash command to launch a new container from an image and switch to an interactive shell within the container. The --interactive or -i parameter along with the --tty or -t parameter are used to allocate a pseudo-TTY within which the Bash shell is run. For example:

~]$ docker run -it registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 bash
bash-4.2$ uname -a
Linux 5e224c8c3878 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux
bash-4.2$ exit
exit

~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  NAMES       COMMAND     STATUS
5e224c8c3878  devtoolset  "uname -a"  Exited (0) 2 seconds ago
[...]

Run the docker rm <container> command to remove one or more containers, thus freeing the host’s resources. For example, to remove the container created in the previous example, use the following command:

~]$ docker rm devtoolset
devtoolset

~]$ docker ps -a | grep devtoolset

To use the oc command on your host system to interact with the OpenShift service running inside the Container Development Kit virtual machine, you need to obtain and install the oc executable.

If you intend to use OpenShift (and the oc command) only from within the Container Development Kit virtual machine, no preparation is required — the oc command is installed in the Container Development Kit box by default.

~]# subscription-manager repos --enable=rhel-7-server-ose-3.2-rpms

~]# yum install -y atomic-openshift-clients

~]$ mkdir ~/openshift

~]$ tar xvzf oc-3.1.1.6-linux.tar.gz --strip=8 -C ~/openshift
mnt/redhat/staging-cds/ose-clients-3.1.1.6/usr/share/atomic-openshift/linux/oc

~]$ export PATH=$PATH:~/openshift

~]$ mkdir ~/openshift

~]$ tar xvzf oc-3.1.1.6-macosx.tar.gz --strip=8 -C ~/openshift
mnt/redhat/staging-cds/ose-clients-3.1.1.6/usr/share/atomic-openshift/macosx/oc

~]$ export PATH=$PATH:~/openshift

C:\Downloads> mkdir C:\Program Files (x86)\openshift

C:\Downloads> cd C:\Program Files (x86)\openshift

C:\Program Files (x86)\openshift> unzip -j oc-3.1.1.6-windows.zip
Archive:  oc-3.1.1.6-windows.zip
  inflating: oc.exe

C:\Program Files (x86)\openshift> set PATH=%PATH%;"C:\Program Files (x86)\openshift"

Upon initializing the Container Development Kit Vagrant box using the rhel-ose Vagrantfile, the following information is output about the OpenShift service that has been provisioned for you:

You can now access the OpenShift console on: https://10.1.2.2:8443/console

To use OpenShift CLI, run:
$ vagrant ssh
$ oc login 10.1.2.2:8443

Configured users are (<username>/<password>):
openshift-dev/devel
admin/admin

If you have the oc client library on your host, you can also login from your host.

The automatically provisioned instance of OpenShift Enterprise in Container Development Kit is provided in the form of a container. You can check that the OpenShift container is installed and running by examining the output of the docker ps command:

~]$ docker ps
CONTAINER ID  IMAGE      COMMAND                 CREATED      STATUS      PORTS  NAMES
...
ddb2d13604ef  openshift  "/usr/bin/openshift s"  2 hours ago  Up 2 hours         openshift

You can also run a health check to determine whether OpenShift is running properly by querying its network interface using the curl command:

~]$ curl -k https://10.1.2.2:8443/healthz
ok

The command-line interface of OpenShift is accessed using the oc command. This command has a number of subcommands that help to interact with various features of the OpenShift service. This section describes how to use the oc command to gather basic information about the current OpenShift instance.

~]$ oc version
oc v3.1.0.4-16-g112fcc4
kubernetes v1.1.0-origin-1107-g4c8e6f4

Use the oc login command to log into specific user profiles. Upon start up, the Container Development Kit box logs you in automatically to the openshift-dev account.

~]$ oc login -u openshift-dev -p devel https://10.1.2.2:8443
The server uses a certificate signed by an unknown authority.
You can bypass the certificate check, but any data you send to the server could be intercepted by others.
Use insecure connections? (y/n): y

Authentication required for https://10.1.2.2:8443 (openshift)
Username: openshift-dev
Password:
Login successful.

You have access to the following projects and can switch between them with 'oc project <projectname>':

  * sample-project (current)

Using project "sample-project".
Welcome! See 'oc help' to get started.

~]$ oc whoami
openshift-dev

~]$ oc config view | grep -A2 "name: openshift-dev"
- name: openshift-dev/10-1-2-2:8443
  user:
    token: THdHS4sw1qgzs95CnCf5ic6D8eOrZss1aT5jyGOmd2w

~]$ oc logout
Logged "openshift-dev" out on "https://10.1.2.2:8443"

In OpenShift, projects are used to organize and manage applications by groups of users. Individual projects keep their content separated from each other, and individual users need to be granted access to projects. Upon start up, the Container Development Kit box automatically creates the sample-project project.

~]$ oc new-project testing --display-name="Test Project"
Now using project "testing" on server "https://127.0.0.1:8443".

You can add applications to this project with the 'new-app' command. For example, try:

    $ oc new-app centos/ruby-22-centos7~https://github.com/openshift/ruby-hello-world.git

to build a new hello-world application in Ruby.

~]$ oc project sample-project
Now using project "sample-project" on server "https://10.1.2.2:8443".

~]$ oc get project
NAME      DISPLAY NAME   STATUS
testing   Test Project   Active

~]$ oc status
In project Test Project (testing) on server https://10.1.2.2:8443

You have no services, deployment configs, or build configs.
Run 'oc new-app' to create an application.

~]$ oc project
Using project "testing" from context named "testing/10-1-2-2:8443/openshift-dev" on server "https://10.1.2.2:8443".

~]$ oc delete project testing
project "testing" deleted

A template in OpenShift is a text file (in the JSON or YAML format) that defines a set of objects. The object definitions, such as services or build configurations, can be parametrized. Templates can be processed to create the objects they describe and thus populate your current project.

To get you quickly started with application development, OpenShift offers a number of basic templates, which are included in the global openshift project. In order to use these templates as the foundation block of a new application, they need to be downloaded from the openshift project and subsequently uploaded to your current project. You can also create a new application (using the oc new-app command) directly from a template.

~]$ oc get templates -n openshift
NAME                                DESCRIPTION                        PARAMETERS     OBJECTS
cakephp-example                     An example CakePHP application...  15 (8 blank)   5
cakephp-mysql-example               An example CakePHP application...  16 (3 blank)   7
eap64-basic-s2i                     Application template for EAP 6...  12 (3 blank)   5
eap64-mysql-persistent-s2i          Application template for EAP 6...  34 (16 blank)  10
jws30-tomcat7-mysql-persistent-s2i  Application template for JWS M...  28 (11 blank)  10
nodejs-example                      An example Node.js application...  12 (8 blank)   5
nodejs-mongodb-example              An example Node.js application...  13 (3 blank)   7

~]$ ls -1 /opt/adb/openshift/templates/common/
cakephp.json
cakephp-mysql.json
eap64-basic-s2i.json
eap64-mysql-persistent-s2i.json
image-streams.json
jboss-image-streams.json
jenkins-ephemeral-template.json
jenkins-persistent-template.json
jenkins-slave-template.json
jws30-tomcat7-mysql-persistent-s2i.json
nodejs.json
nodejs-mongodb.json
wildfly-image-streams.json

~]$ oc get templates -o json -n openshift nodejs-mongodb-example \ > nodejs-mongodb-example.json

~]$ ls
nodejs-mongodb-example.json

~]$ oc create -f nodejs-mongodb-example.json -n testing
the namespace from the provided object "openshift" does not match the namespace "testing". You must pass '--namespace=openshift' to perform this operation.

{
    "kind": "Template",
    "apiVersion": "v1",
    "metadata": {
        "name": "nodejs-mongodb-example",
        "namespace": "testing",
[...]

~]$ oc create -f nodejs-mongodb-example.json
template "nodejs-mongodb-example" created

~]$ oc get templates
NAME                     DESCRIPTION                                              PARAMETERS     OBJECTS
nodejs-mongodb-example   An example Node.js application with a MongoDB database   11 (3 blank)   7

~]$ oc process --parameters nodejs-mongodb-example
NAME                     DESCRIPTION                              GENERATOR   VALUE
SOURCE_REPOSITORY_URL    The URL of the repository with your...               https://github.com/openshift/nodejs-ex.git
SOURCE_REPOSITORY_REF    Set this to a branch name, tag or ot...
CONTEXT_DIR              Set this to the relative path to you...
APPLICATION_DOMAIN       The exposed hostname that will route...
GITHUB_WEBHOOK_SECRET    A secret string used to configure th...  expression  [a-zA-Z0-9]{40}
GENERIC_WEBHOOK_SECRET   A secret string used to configure th...  expression  [a-zA-Z0-9]{40}
DATABASE_SERVICE_NAME    Database service name                                         mongodb
DATABASE_USER            Username for MongoDB user that will...   expression  user[A-Z0-9]{3}
DATABASE_PASSWORD        Password for the MongoDB user            expression  [a-zA-Z0-9]{16}
DATABASE_NAME            Database name                                        sampledb
DATABASE_ADMIN_PASSWORD  Password for the database admin user...  expression  [a-zA-Z0-9]{16}

~]$ oc process nodejs-mongodb-example \
-v SOURCE_REPOSITORY_URL=https://github.com/username/nodejs-ex.git | \
oc create -f -
service "nodejs-mongodb-example" created
route "nodejs-mongodb-example" created
imagestream "nodejs-mongodb-example" created
buildconfig "nodejs-mongodb-example" created
deploymentconfig "nodejs-mongodb-example" created
service "mongodb" created
deploymentconfig "mongodb" created

To use a template to directly create a new application, run the oc new-app command with the --template option specifying the template you want to use as the basis for your application. For example, to use the nodejs-example InstantApp template, run the following command:

~]$ oc new-app --template=nodejs-example
--> Deploying template nodejs-example in project openshift for "nodejs-example"
     With parameters:
      Memory Limit=512Mi
      Git Repository URL=https://github.com/openshift/nodejs-ex.git
      Git Reference=
      Context Directory=
      Application Hostname=
      GitHub Webhook Secret=UKWP4bVymgjXcNMVnHIdaVeaORt3NMPuyqAEHhLv # generated
      Generic Webhook Secret=wabGtSM7g5eSykRuH5aCskWKdFOXB0UxyNNrnQyr # generated
      Database Service Name=
      MongoDB Username=
      MongoDB Password=
      Database Name=
      Database Administrator Password=
--> Creating resources with label app=nodejs-example ...
    Service "nodejs-example" created
    Route "nodejs-example" created
    ImageStream "nodejs-example" created
    BuildConfig "nodejs-example" created
    DeploymentConfig "nodejs-example" created
--> Success
    Build scheduled for "nodejs-example" - use the logs command to track its progress.
    Run 'oc status' to view your app.

To monitor the progress of the deployment, use the oc status command, optionally with the -v (--verbose) parameter to display information about potential warnings:

~]$ oc status -v
In project OpenShift sample project (sample-project) on server https://127.0.0.1:8443

svc/nodejs-example - 172.30.142.222:8080
  dc/nodejs-example deploys imagestreamtag/nodejs-example:latest <-
    bc/nodejs-example builds https://github.com/openshift/nodejs-ex.git with openshift/nodejs:0.10
      #1 build running for 27 seconds
    #1 deployment waiting on image or update
  exposed by route/nodejs-example

Warnings:
  * The image trigger for dc/nodejs-example will have no effect until imagestreamtag/nodejs-example:latest is imported or created by a build.

View details with 'oc describe <resource>/<name>' or list everything with 'oc get all'.

The application is automatically deployed when the build completes. Use the oc describe command to display information about different parts of the application (or use the oc get all command to display all information at once).

To see summary information about the service, use:

~]$ oc describe svc/nodejs-example
Name:                   nodejs-example
Namespace:              sample-project
Labels:                 app=nodejs-example,template=nodejs-example
Selector:               name=nodejs-example
Type:                   ClusterIP
IP:                     172.30.142.222
Port:                   web     8080/TCP
Endpoints:              172.17.0.2:8080
Session Affinity:       None
No events.

To display information about the route established for the application, use:

~]$ oc describe route/nodejs-example
Name:                   nodejs-example
Created:                46 minutes ago
Labels:                 app=nodejs-example,template=nodejs-example
Annotations:            openshift.io/generated-by=OpenShiftNewApp
                        openshift.io/host.generated=true
Host:                   nodejs-example-sample-project.rhel-cdk.10.1.2.2.xip.io
Path:                   <none>
Service:                nodejs-example
TLS Termination:        <none>
Insecure Policy:        <none>

The above command shows that the deployed application can be accessed at nodejs-example-sample-project.rhel-cdk.10.1.2.2.xip.io (the URL is made available through the external xip.io DNS service).

You can point a web browser from your host system at this address to see the page generated by the application. To check whether the application is running properly from the command line, either use a text-mode browser like lynx or download the page using curl:

~]$ curl nodejs-example-sample-project.rhel-cdk.10.1.2.2.xip.io 2> /dev/null | grep '<h1>'
            <h1>Welcome to your Node.js application on OpenShift</h1>

To check the Docker images and containers that form the application, use the docker images and docker ps commands:

~]$ docker images
REPOSITORY                                        TAG     IMAGE ID      CREATED      VIRTUAL SIZE
172.30.254.28:5000/sample-project/nodejs-example  latest  bc19f3f7dd86  2 hours ago  432.6 MB
172.30.254.28:5000/sample-project/nodejs-example  <none>  bc19f3f7dd86  2 hours ago  432.6 MB

[...]

~]$ docker ps
CONTAINER ID  IMAGE                                                        COMMAND                 CREATED      STATUS      NAMES
bcafafb013ce  172.30.254.28:5000/sample-project/nodejs-example@sha256:...  "container-entrypoint"  2 hours ago  Up 2 hours  k8s_nodejs-example.27445d76_nodejs-example-1-hdq11_sample-project_e5c69b57-0496-11e6-907d-525400806d1b_3e6e6b39
d4f52a47cb10  openshift3/ose-pod:v3.1.1.6                                  "/pod"                  2 hours ago  Up 2 hours  k8s_POD.5983fd1a_nodejs-example-1-hdq11_sample-project_e5c69b57-0496-11e6-907d-525400806d1b_b3dee3ea

[...]

Create a new repository on GitHub. For the purposes of this example, we will assume that the created repository has the following URL: http://github.com/example/nodejs-hello-world.git. Then upload a basic Node.js application to the root directory of the repository. Name the file helloworld.js.

var http = require('http');

var server = http.createServer(function(req, res) {
  res.writeHead(200);
  res.end('Hello World');
});
server.listen(8080);

The application creates an HTTP server listening on port 8080 and prints Hello World when accessed. Download the helloword.js file.

Upload the following minimal definition of a Node.js OpenShift application to the GitHub repository. Name the file package.json. Based on the name of the file, OpenShift automatically selects the appropriate builder (nodejs, in this case).

{
  "name": "nodejs-hello-world",
  "version": "0.0.1",
  "description": "Node.js Hello World for OpenShift 3",
  "main": "helloworld.js", 1
  "dependencies": {
    "ejs": "^2.4.1", 2
    "express": "^4.13.4"
  },
  "scripts": {
    "start": "node helloworld.js" 3
  },
  "repository": {
    "type": "git",
    "url": "http://github.com/rkratky/nodejs-hello-world.git"
  }
}

Download the package.json file.

To create a new application in OpenShift, use the oc new-app command. OpenShift automatically performs the following steps:

In this example, the required Node.js container image from the Red Hat Atomic Registry is specified along with the URL of the Git repository:

~]$ oc new-app registry.access.redhat.com/openshift3/nodejs-010-rhel7~https://github.com/example/nodejs-hello-world.git
--> Found Docker image 92eee82 (6 weeks old) from registry.access.redhat.com for "registry.access.redhat.com/openshift3/nodejs-010-rhel7"
    * An image stream will be created as "nodejs-010-rhel7:latest" that will track the source image
    * A source build using source code from https://github.com/example/nodejs-hello-world.git will be created
      * The resulting image will be pushed to image stream "nodejs-hello-world:latest"
      * Every time "nodejs-010-rhel7:latest" changes a new build will be triggered
    * This image will be deployed in deployment config "nodejs-hello-world"
    * Port 8080/tcp will be load balanced by service "nodejs-hello-world"
--> Creating resources with label app=nodejs-hello-world ...
    ImageStream "nodejs-010-rhel7" created
    ImageStream "nodejs-hello-world" created
    BuildConfig "nodejs-hello-world" created
    DeploymentConfig "nodejs-hello-world" created
    Service "nodejs-hello-world" created
--> Success
    Build scheduled for "nodejs-hello-world" - use the logs command to track its progress.
    Run 'oc status' to view your app.

Use the oc describe build command to display information about the build currently in progress:

~]$ oc describe build
Name:           nodejs-hello-world-1
Created:        35 seconds ago
Labels:         app=nodejs-hello-world,buildconfig=nodejs-hello-world,openshift.io/build-config.name=nodejs-hello-world
Annotations:    openshift.io/build.number=1
                openshift.io/build.pod-name=nodejs-hello-world-1-build
Build Config:   nodejs-hello-world
Started:        2016-04-18 07:05:25 -0400 EDT
Duration:       running for 25s
Build Pod:      nodejs-hello-world-1-build
Strategy:       Source
URL:            https://github.com/rkratky/nodejs-hello-world.git
From Image:     DockerImage registry.access.redhat.com/openshift3/nodejs-010-rhel7:latest
Output to:      ImageStreamTag nodejs-hello-world:latest
Push Secret:    builder-dockercfg-9000s
Status:         Running
Events:
  FirstSeen     LastSeen    Count   From                SubobjectPath                      Reason     Message
  ─────────    ────────   ─────   ────               ─────────────                     ──────     ───────
  34s           34s         1       {scheduler }                                           Scheduled  Successfully assigned nodejs-hello-world-1-build to rhel-cdk
  32s           32s         1       {kubelet rhel-cdk}  implicitly required container POD  Pulled     Container image "openshift3/ose-pod:v3.1.1.6" already present on machine
  30s           30s         1       {kubelet rhel-cdk}  implicitly required container POD  Created    Created with docker id 462325c7c721
  29s           29s         1       {kubelet rhel-cdk}  implicitly required container POD  Started    Started with docker id 462325c7c721
  29s           29s         1       {kubelet rhel-cdk}  spec.containers{sti-build}         Pulled     Container image "openshift3/ose-sti-builder:v3.1.1.6" already present on machine
  27s           27s         1       {kubelet rhel-cdk}  spec.containers{sti-build}         Created    Created with docker id f5bcba8891c3
  26s           26s         1       {kubelet rhel-cdk}  spec.containers{sti-build}         Started    Started with docker id f5bcba8891c3

To see the build logs, use the oc logs command and specify the build you are interested in:

~]$ oc logs build/nodejs-hello-world-1
---> Installing application source
---> Building your Node application from source
E0418 09:17:59.264104  1 util.go:91] npm info it worked if it ends with ok
E0418 09:17:59.265357  1 util.go:91] npm info using npm@2.14.13
E0418 09:17:59.265366  1 util.go:91] npm info using node@v0.10.40
E0418 09:18:00.697173  1 util.go:91] npm WARN package.json nodejs-hello-world@0.0.1 No license field.
E0418 09:18:00.720236  1 util.go:91] npm info preinstall nodejs-hello-world@0.0.1
E0418 09:18:00.828498  1 util.go:91] npm info attempt registry request try #1 at 09:18:00

[...]

Use the oc describe command and specify the service you are interested in to show summary information about the created service:

]$ oc describe svc/nodejs-hello-world
Name:              nodejs-hello-world
Namespace:         sample-project
Labels:            app=nodejs-hello-world
Selector:          app=nodejs-hello-world,deploymentconfig=nodejs-hello-world
Type:              ClusterIP
IP:                172.30.166.144
Port:              8080-tcp        8080/TCP
Endpoints:         172.17.0.4:8080
Session Affinity:  None
No events.

Similarly, you can specify the deployment to show information about it, including the containers that have been created and deployed for the application:

~]$ oc describe dc
Name:           nodejs-hello-world
Created:        2 minutes ago
Labels:         app=nodejs-hello-world
Annotations:    openshift.io/generated-by=OpenShiftNewApp
Latest Version: 1
Triggers:       Config, Image(nodejs-hello-world@latest, auto=true)
Strategy:       Rolling
Template:
  Selector:     app=nodejs-hello-world,deploymentconfig=nodejs-hello-world
  Replicas:     1
  Containers:
  NAME                  IMAGE                                                                                                                           ENV
  nodejs-hello-world    172.30.91.119:5000/sample-project/nodejs-hello-world@sha256:d97a0c44759c93b4231691813c12b5d2975c78fbee028f6c0091d97ed3816678
Deployment #1 (latest):
  Name:         nodejs-hello-world-1
  Created:      2 minutes ago
  Status:       Complete
  Replicas:     1 current / 1 desired
  Selector:     app=nodejs-hello-world,deployment=nodejs-hello-world-1,deploymentconfig=nodejs-hello-world
  Labels:       app=nodejs-hello-world,openshift.io/deployment-config.name=nodejs-hello-world
  Pods Status:  1 Running / 0 Waiting / 0 Succeeded / 0 Failed
No events.

To verify that the deployed HTTP server works correctly and serves the message specified in the application source code, you can use, for example, the curl tool:

~]$ curl 172.17.0.4:8080
Hello World

The IP address is shown, for example, in the description of the deployed service or pod. Use the oc get pods to list all pods:

~]$ oc get pods
NAME                         READY   STATUS      RESTARTS   AGE
nodejs-hello-world-1-1b5xi   1/1     Running     0          2m
nodejs-hello-world-1-build   0/1     Completed   0          2m

Use the name of the pod to display its description and grep for its IP address:

~]$ oc describe pod/nodejs-hello-world-1-1b5xi | grep IP
IP:                             172.17.0.4