General setup

Ideally, you should try the tutorials using a realistic OpenShift cluster—for example, one deployed to Amazon Web Services, Google Cloud Platform, or Azure. This provides a more realistic demonstration and relieves you from the constraints of local machine resources. However, if this is not feasible, perhaps due to the hosting cost, you can follow this guide using Minishift running locally.

Minishift has some significant limitations around resources such as memory and CPU. In some cases, you will have to deploy with only one replica, when in production you should really use at least three. If running multiple microservices, you will have to assign only small fractions of CPU resources to each, and this slows down the start up process.

We will generate several passwords using ssl. To follow the tutorial with a Java application, we recommend using a JDK supported by Lightbend. If you do not already have them installed, the sections on this page provide links for obtaining ssl, a supported JDK, OpenShift, and Minishift.

Obtaining ssl

Several open source ssl libraries are available. You can download OpenSSL from https://www.openssl.org.

Using a supported JDK

By default, sbt native packager uses the openjdk latest Docker image from DockerHub. At time of writing, this will give you OpenJDK 11, and the Debian OpenJDK build, neither of which are certified by Lightbend. See the full list of Lightbend certified JDK builds and versions.

If you’re a RedHat customer, then you will probably want to use RedHat’s certified OpenJDK base image, which is using RHEL. These OpenJDK builds are also certified by Lightbend for use with Lightbend products. Otherwise, we recommend installing and using the AdoptOpenJDK base image.

Setting up OpenShift

You will need to have the OpenShift or OKD client installed on your local machine to run oc commands.

If, in addition, you need to install OpenShift, follow the official instructions for installing the distribution of your choice:

  • OKD - the open source distribution of OpenShift

  • OpenShift Container Platform - RedHat’s commercially supported OpenShift distribution that requires a license

  • Minishift - the development distribution of OpenShift that allows you to run on your local machine

The Lightbend Platform for OpenShift is tested and supported on OpenShift 3.11.

Accessing a Docker Registry

Your environment must be configured to push Docker images to the default cluster registry. The registry must be reachable from your local machine. In many cases, this requires exposing your OpenShift installation’s internal registry to the outside world and logging in. Typically, once this is done, your docker registry will be available at a URL similar to: docker-registry-default.myopenshift.example.com.

If OpenShift has been set up and configured for you, contact the administrator to get the URL. On the other hand, if you are setting up your own cluster, see the link above to make sure that you’ve addressed this.

Running Minishift

If you must use Minishift, we recommend you configure it with more resources than the default 2GB of RAM and 2 CPUs. If you also use Minishift for other purposes, you may want to create a custom profile for the examples in this guide. You can also pass a memory argument when you start Minishift, but with a profile, you do not have to remember to pass the argument every time you delete and restart your Minishift instance.

Create a custom profile named lightbend as follows:

  1. Create and enable the profile:

    minishift profile set lightbend

  2. Configure how much RAM should be allocated to Minishift, let’s allocate it 6GB:

    minishift config set memory 6GB

  3. Start Minishift:

    minishift start

  4. Ensure that the oc binary is on your path, and that your environment is configured to use the Minishift VMS docker host:

    eval $(minishift oc-env) (1)
eval $(minishift docker-env) (2)
    1 Modifies your PATH to include the oc binary.
    2 Sets DOCKER_* environment variables to tell Docker which host to use and how to authenticate when building images.
Since these commands just modify environment variables in your current shell session, you need to rerun them if you open a new terminal window, or any time you delete and restart your Minishift instance.

What’s next

Choose one of the following examples: