Getting Started

This document walks you through the development and deployment of a Node.js application to an OpenShift cluster using odo. It guides you on how to push new changes to your application and on other useful features of odo.

Developing and deploying an application to an OpenShift cluster

To develop and deploy a Node.js application to an OpenShift cluster using odo:

  1. Install the odo binary.

  2. Log into an OpenShift cluster:

    • If you lack a local development cluster, we recommend using Minishift to deploy a development OpenShift cluster.

      1. Run Minishift:

        $ minishift start
      2. Log into the OpenShift cluster:

        $ odo login -u developer -p developer
        Note

        In order to make full use of odo functionality, it is recommended to enable the OpenShift service catalog. See using service catalog section for more details.

    • If you do not use Minishift, odo automatically works with any OpenShift cluster you are currently logged into. To log into the OpenShift cluster run:

      $ odo login -u developer -p developer
  3. An application is an umbrella that comprises of all the components (microservices) you build. Create a component as follows:

    1. Download the sample application and change directory to the location of the application:

      $ git clone https://github.com/openshift/nodejs-ex
      $ cd nodejs-ex
    2. Add a component of the type nodejs to the application:

      $ odo create nodejs
      Note
      By default, the latest image is used. You can also explicitly supply an image version by using odo create openshift/nodejs:8.
    3. Push the initial source code to the component:

      $ odo push

      Your component is now deployed to OpenShift.

  4. Create a URL and add an entry in the local configuration file as follows:

    $ odo url create --port 8080
  5. Push the changes. This creates a URL on the cluster.

    $ odo push
  6. List the URLs to check the desired URL for the component.

    $ odo url list
  7. View your deployed application using the generated URL.

    $ curl <URL>
  8. Edit your code and push the changes to the component:

    1. Edit one of the layout files within the Node.js directory.

      $ vim views/index.html
    2. Push the changes:

      $ odo push
    3. Refresh your application in the browser to see the changes.

After each change, you can update your component using: odo push.

Other key odo features

Adding storage to the component

odo enables you to persist data between restarts by making it easy to add storage to your component as follows:

$ odo storage create nodestorage --path=/opt/app-root/src/storage/ --size=1Gi

This adds storage to your component with an allocated size of 1 Gb.

Using command completion

Note
  • Currently command completion is only supported for bash, zsh and fish shells.

  • If you either rename the odo executable or move it, the completion system stops working and you will need to re-enable it accordingly.

odo provides smart completion of command parameters based on user input. For this to work, odo needs to integrate with the executing shell.

  • To install command completion automatically, run odo --complete and press y when asked to install the completion hook.

  • To install the completion hook manually add complete -o nospace -C <full path to your odo binary> odo to your shell configuration file (e.g. .bashrc for bash).

  • To disable completion, run odo --uncomplete.

After any modification to your shell configuration file, you will need to source it or restart your shell.

Using the .odoignore and .gitignore files

The .odoignore file in the root directory of your application is used to ignore a list of files/patterns. This applies to both odo push and odo watch.

If the .odoignore file does not exist, the .gitignore file is used instead for ignoring specific files and folders.

For example, to ignore .git files, any files with the .js extension, and the folder tests, add the following to either the .odoignore or the .gitignore file:

.git
*.js
/tests

The .odoignore file allows any glob expressions to be used, for example you can use the following:

/openshift/**/*.json

Using Service Catalog with odo

If you use Minishift, you require version 1.22 or above.

In order to use the Service Catalog it must be enabled within your OpenShift cluster.

  1. Start an OpenShift cluster, version 3.10 and above.

  2. Enable the Service Catalog:

    $ MINISHIFT_ENABLE_EXPERIMENTAL=y minishift start --extra-clusterup-flags "--enable=*,service-catalog,automation-service-broker"
  3. After you enable or start minishift:

    • To list the services, use:

      $ odo catalog list services
    • To list service catalog related operations, use:

      $ odo service <verb> <servicename>

Adding a custom builder

OpenShift enables you to add a custom image to bridge the gap between the creation of custom images. A custom builder image usually includes the base image of openshift/origin-custom-docker-builder.

The following example demonstrates the successful import and use of the redhat-openjdk-18 image:

Prerequisites:

oc binary is installed and present on the $PATH.

Procedure:
  1. Import the image into OpenShift:

    $ oc import-image openjdk18 --from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift --confirm
  2. Tag the image to make it accessible to odo:

    $ oc annotate istag/openjdk18:latest tags=builder
  3. Deploy it with odo:

    $ odo create openjdk18 --git https://github.com/openshift-evangelists/Wild-West-Backend