Skip to content

Using the Default Starter

Jump to bottom
Edward Mezarina edited this page Nov 17, 2021 · 3 revisions

The Open Liberty stack provides a bare-bones starter application. The intent of this starter is to provide a starting point for developing your app with minimal need to change or delete files. For a more complete sample application, check out the devfile-stack-intro project.

For a lot more detail on the odo commands, check out: http://odo.dev

Default starter

The default starter provides a pom.xml file that enables Liberty features that support Eclipse MicroProfile 3.3. Specifically, this template includes:

Health

The mpHealth feature allows services to report their readiness and liveness status - UP if it is ready or alive and DOWN if it is not ready/alive. It publishes two corresponding endpoints to communicate the status of liveness and readiness. A service orchestrator can then use the health statuses to make decisions.

Liveness endpoint: http://<host>:<port>/health/live Readiness endpoint: http://<host>:<port>/health/ready

Metrics

The mpMetrics feature enables MicroProfile Metrics support in Open Liberty. You can monitor metrics to determine the performance and health of a service. You can also use them to pinpoint issues, collect data for capacity planning, or to decide when to scale a service to run with more or fewer resources.

Metrics endpoint: http://<host>:<port>/metrics

Note: This feature requires SSL, configured for you, plus some extra configuration in order to access the /metrics endpoint from an external client.

Metrics Password

Security for the development image is enabled via Open Liberty's <quickStartSecurity> configuration. This mechanism provides a basic username/password to the server and is intended for development. It is intentionally removed when an official production image is built.

Log in as the admin user to see both the system and application metrics in a text format. The password for this admin user will be generated by the container.

To get the generated password for your project, you can exec in the container via:

$ odo exec -- bash -c "grep keystore /projects/target/liberty/wlp/usr/servers/defaultServer/server.env"

keystore_password=2r1aquTO3VVUVON7kCDdzno

So in this example the password value would be: 2r1aquTO3VVUVON7kCDdzno. You can now access the metrics endpoint from within the container via:

$ odo exec -- curl https://localhost:9443/metrics -u admin:2r1aquTO3VVUVON7kCDdzno --insecure

Junit 5

The default template uses JUnit 5. You may be used to JUnit 4, but here are some great reasons to make the switch https://developer.ibm.com/dwblog/2017/top-five-reasons-to-use-junit-5-java/

Getting Started

  1. Perform an oc login to your Open Shift cluster for development purposes.

  2. Install the latest vesion of OpenShift Do (odo) using these instructions

  3. Create a new folder in your local directory and create an odo project using the odo CLI, e.g.:

    mkdir my-project
cd my-project
odo project create <project namespace name>

    The project namespace name will be used to create an OpenShift namespace that will house your application and related pods

  4. Initialize the local folder using the Open Liberty stack.

    odo create java-openliberty --starter user-app

    This will initialize an Open Liberty project and download the default starter app artifacts.

  5. Once your project has been initialized, you can push your application to your OpenShift cluster for the first time using the following command:

    odo push

    Upon a first time odo push invocation, the following occurs:

    • An Open Shift managed Kubernetes pod is launched within the namespace created in step 3 above,
    • A container based on the image referenced in the devfile is started in that pod
    • odo syncs your local source code directory to that container. (under the /projects directory)
    • The app is compiled and built within the container and liberty dev mode is started to host the app once built.
    • A URL is activated and is usable to access the app

  6. Retrieve the URL for your app using the odo CLI:

    odo url list

  7. You should be able to access the following endpoints, as they are exposed by your template application by default:

    • Readiness endpoint: http://<odo url>/health/ready
    • Liveness endpoint: http://<odo url>>/health/live
    • Metrics endpoint: http://<odo url>/metrics (To use this endpoint you need some extra configuration to create a "secure route". Then login as admin user with password obtained as mentioned here.

To see source code changes reflected in the running application you can re-issue the odo push command after any edit session is complete and saved. Source code changes will be reflected in the running container within a few seconds. Alternatively, you can issue odo watch once which will monitor for changes in your local project and automatically push changes to your remote cluster.

FURTHER READING

  • For a lot more detail on the odo commands, check out: http://odo.dev
Clone this wiki locally