openliberty / iguide-microprofile-config-intro

Open Liberty MicroProfile Config Guide: https://openliberty.io/guides/microprofile-config-intro.html

iguide-microprofile-config

Link to the guide on Openliberty.io: https://openliberty.io/guides/microprofile-config-intro.html

This repo provides an interactive guide on the Openliberty.io website that users can interact with and learn more about different concepts related to Open Liberty.

What you'll learn:

Learn how to use MicroProfile Config to separate configuration from code. Explore how to inject configuration data into a microservice without repackaging the application each time the underlying runtime environment changes. MicroProfile makes building configurable microservices easy with its MicroProfile Config feature. Application configuration properties from multiple sources are combined into a single set of configuration properties and accessed from a single API by your application.

Using the MicroProfile Config API, the sample application illustrates how a configuration property can be assigned a value in multiple configuration sources. Each source is assigned a priority. The value from the source with the highest priority takes precedence over that from a lower priority. This method allows code to run unchanged under different configurations for development, test, quality assurance, and production environments since an existing configuration value can easily be overridden as the need arises.

iguide-microprofile-config-intro's Issues

Fix accessibility issues

• Make config properties table accessible (tested with JAWS)
• Run DAP on all pages of the guide

Environment variables from the command line

There's a small sentence mentioning that env variables can be passed from the command line. Could I see an example of that? I can't seem to get anything working :(
My setup:

• simple dockerized microservice based on open-liberty:microProfile1-java8-ibm
• need an env var that's configurable at runtime
• I have defined this property in the microprofile-config.properties file, but I need to overwrite it when I do "docker run my_image"

https://www.ibm.com/support/knowledgecenter/en/SSAW57_8.5.5/com.ibm.websphere.wlp.nd.doc/ae/twlp_admin_customvars.html mentions also that "You can also specify these environment variables in the shell environment, but the server.env files take precedence over those variables."... sadly, again there isn't an example.

UPDATE:
My somewhat clumsy workaround to this is:

• define ENTRYPOINT in my own Dockerfile, overwriting the one in the microprofile parent image like so:

ENTRYPOINT java -DMY_VAR=$MY_VAR -javaagent:/opt/ol/wlp/bin/tools/ws-javaagent.jar -jar /opt/ol/wlp/bin/tools/ws-server.jar defaultServer

• run the container with my env var set at runtime:

docker run -e MY_VAR=foobar my_image

Feels kind of odd to do this though...

target="_blank" link problem reported by AppScan

Change all the occurrences of
<a href="..." target="_blank">
to
<a href="..." target="_blank" rel="noopener noreferrer">

Update sample readme for start/stop server command

The sample readme should replace the instruction to start/stop server from liberty server command to maven command.

Jekyll build break due to regular expression

Problem

I have confirmed that the error below is showing up when building the staging website (openlibertydev.mybluemix.net) with the interactive microprofile config guide. I was able to recreate this error locally.

Build Error

Configuration file: src/main/content/_config.yml
            Source: src/main/content
       Destination: target/jekyll-webapp
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    SyntaxError: Invalid regular expression: /(?<=\().*(?=\))/: Invalid group
  Liquid Exception: SyntaxError: Invalid regular expression: /(?<=\().*(?=\))/: Invalid group in /_layouts/default.html
jekyll 3.6.2 | Error:  SyntaxError: Invalid regular expression: /(?<=\().*(?=\))/: Invalid group

Finished: FAILED

Console errors on playground

Steps

• Go to https://openlibertydev.mybluemix.net/guides/microprofile-config-intro.html#default-configsources-playground
• Observe first error in console tab
  
• Click Run button
• Observe second error in console tab
  

Config props table goes off page with long property name

Guide needs an unique permalink

Problem

Both the static and interactive MPConfig guides have the same permalink of guides/microprofile-config. Permalinks must be unique.

Observe that both the interactive and static MPConfig guide cards go to the interactive guide. MPConfig static guide is not reachable.
https://qa-guides.mybluemix.net/guides/

Change all properties to use port

with the new scenario we'll be using port property

Step to change the ordinal of a property config source

By default, a META-INF/microprofile-config.properties has a ordinal of 100. However, ordinal value could be overridden by using the config_ordinal property. Eg.

download_url=ftp://music.com/us-south/download
config_ordinal=500

Dismiss error message across all Playground editor tabs

When an error message is shown in the playground tabbed editor, it is displayed across all the tabs. They will all clear simultaneously when the error is fixed.

Currently when the error is dismissed with the X button, it only dismisses the error message in the current editor, but should dismiss them from all the editor tabs.

DeploymentException should be exposed thru start server or app not through a web browser

This issue is to fix the DeploymentException on the injection with no default step. The DeploymentException is from starting the app, not from running the app. Here's the error when starting the server:

[lavena@Lavenas-MacBook-Pro:bin]$ ./server run defaultServer
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0
objc[73726]: Class JavaLaunchHelper is implemented in both /Library/Java/JavaVirtualMachines/jdk1.8.0_144.jdk/Contents/Home/jre/bin/java (0x100c224c0) and /Library/Java/JavaVirtualMachines/jdk1.8.0_144.jdk/Contents/Home/jre/lib/libinstrument.dylib (0x100d1c4e0). One of the two will be used. Which one is undefined.
Launching defaultServer (Open Liberty 17.0.0.3/wlp-1.0.18.cl170320170927-1854) on Java HotSpot(TM) 64-Bit Server VM, version 1.8.0_144-b01 (en_US)
[AUDIT ] CWWKE0001I: The server defaultServer has been launched.
[AUDIT ] CWWKZ0058I: Monitoring dropins for applications.
[WARNING ] CWNEN0057W: The io.openliberty.guides.microprofile.InventoryConfig.portNumber injection target must not be declared static.
[ERROR ] CWMCG5003E: The [BackedAnnotatedField] @Inject @configproperty private io.openliberty.guides.microprofile.InventoryConfig.downloadUrl InjectionPoint dependency was not resolved. Error: java.util.NoSuchElementException: CWMCG0015E: The property download_url was not found in the configuration.
at com.ibm.ws.microprofile.config.impl.AbstractConfig.getValue(AbstractConfig.java:129)
at [internal classes]

[ERROR ] CWMCG5003E: The [BackedAnnotatedField] @Inject @configproperty private io.openliberty.guides.microprofile.InventoryConfig.downloadUrl InjectionPoint dependency was not resolved. Error: java.util.NoSuchElementException: CWMCG0015E: The property download_url was not found in the configuration.
at com.ibm.ws.microprofile.config.impl.AbstractConfig.getValue(AbstractConfig.java:129)
at [internal classes]

[ERROR ] CWWKZ0002E: An exception occurred while starting the application io.openliberty.guides.microprofile.mpconfig. The exception message was: com.ibm.ws.container.service.state.StateChangeException: org.jboss.weld.exceptions.DeploymentException: WELD-001408: Unsatisfied dependencies for type String with qualifiers @configproperty
at injection point [BackedAnnotatedField] @Inject @configproperty private io.openliberty.guides.microprofile.InventoryConfig.downloadUrl
at io.openliberty.guides.microprofile.InventoryConfig.downloadUrl(InventoryConfig.java:0)

[AUDIT ] CWWKF0012I: The server installed the following features: [servlet-3.1, jndi-1.0, json-1.0, cdi-1.2, jsonp-1.0, mpConfig-1.1, jaxrs-2.0, jaxrsClient-2.0].
[AUDIT ] CWWKF0011I: The server defaultServer is ready to run a smarter planet.

ID edits for the interactive guide, "Using MicroProfile Config for static configuration injection"

Link to the Box Note that contains edits for the interactive guide: https://ibm.ent.box.com/notes/256011230348

Fix timing issue in playground

If you load the guide from default http://localhost:4000/guides/microprofile-config-intro.html in a new tab to not use session storage, it has a bug that looks like the playground callback didn't load properly.

Add the example application

Adding the example app that matches the code in the interactive guide.

What you'll learn + Background

Config values can be specified as system properties, environment variables, or in configsources. @configproperty qualifier - naming the variable
Default ConfigSources
A Microprofile-Config implementation must provide ConfigSources for the following data out of the
box:
• System properties (default ordinal=400).
• Environment variables (default ordinal=300).
• A ConfigSource for each property if existed under META-INF\microprofile-config.properties

Feedback item updates to the Microprofile Config guide

Following the review of the Circuit Breaker guide in (Issue 75 in iguide-circuitBreaker), make similar changes to the the Microprofile Config guide.

• 'Enabling MicroProfile Fault Tolerance step - reiterate why we are adding in fault tolerance to our application and indicate that this is how to add the feature in WAS Liberty.

Update sample application README for MP-Config

Received the ID updates for MP-Config. Add these updates to the current README.TXT file for the sample appliation.

Also, change to updating all files in the src directory and then issuing mvn_package to restart the server and restart the application for the changes to take effect.

[Step 4] Inject using System Property

Use system property (default ordinal = 400)

Feedback #4 to address from the playback

Background concepts

• Java CDI is not a thing, drop the word Java because the actual name is Context Dependency Injection.

Devops Pipeline example:

• Add description of the example saying that there are 4 ports on 1 application running on 1 Liberty
• Show a diagram with the different ports and what values of cars will be returned from each like on the whiteboard.
  --> Pic was sent to Murphy; Initial draft due 12/5 to us.
  --> This should replace the words on the Example step, but may have to be careful that with accessibility it can still be read correctly.
  --> Implemented as an SVG
• 'For performance and security reasons...' -> 'For stability and security reasons....'
• capitalize the 'd' on displayCarTypes ... it's not correct on one of them.

Injecting @ConfigProperty

• Verify the stack trace is correct after getting a working version of the code. Is jboss really included in the stack trace?
  --> Trace was verified with Annie. Michal to double check when he has a working sample application going.

Providing default values with injection step:

• Improve the url domain to not be a potential car site, it can just be 'localhost'
  --> Michal to verify with legal that we can use 'mycarvendor.openliberty.io'
• Do not use 'foo' and 'bar', use actual car types
• Add to the instruction which values are going to be expected from the development port.
  Something like 'Because this request is for our development server, we are expecting back the values of....' within the green instruction.
• Do not use sedan, it is not valid in the U.K.

Configuring with properties file step:

• If there are multiple microprofile-config.properties files, how does Open Liberty decide which to use?
  --> Sent a note to Emily on 12/4. Copied Michal and Dana as requested.
  --> See note below in another comment on this topic
  --> Emily's response is posted below. The value used if set in more than one microprofile-config.properties file is indeterminate.
  --> A paragraph will be added to the configure with properties file page.
• Add to the instruction which values are going to be expected from the development port.

Configuring with an environment variable step:

• Copy button is the same as reset OpenLiberty/iguides-common#75
• Take sedan out of the car list (not fully translatable - UK uses saloon)
• Add to the instruction which values are going to be expected from the development port.
• You can also set an environment variable on the command line. Information on this should be included.

Configuring using a system property step:

• Remove note and incorporate it into the paragraph above it.
• Do not mention that bootstrap.properties does not exist until you create it, because none of the files exist by default.
• Add to the instruction which values are going to be expected from the development port.

Changing ordinal step:

• In the instruction, mention that 500 is the highest value because the user might not remember that 400 was the highest used by default.

Overall....

• Work with the static guide owners to use the same application between the two guides. We will only have the port property to set. They should include the port property in their sample app, even if they don't talk about it.
  --> Michal is currently working on the sample application.
• Should we show an image on each configure step to illustrate where the values are coming from?
  --> Murphy provided a simple image which we are going to try out directly following the instructions.
  --> The review on 12/8 resulted in no further image needed. Updates to the status bar on the web page was sufficient.
• Should a method showing that the port is being used be part of the example in the editor?
• 'music-download' still appears in our callback.js. Remove code if not in use or correct the comments.
• Get the editor and the browser to be the same size. Watch that the size of the editor outside of a tabbedEditor has the filename header preprended to the editor widget!

Update java code in editor

Update the java code in the editors to the following:

package io.openliberty.guides.mpconfig;

import javax.inject.Inject;
import javax.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
public class InventoryConfig {

  @Inject
  @ConfigProperty(name="port", defaultValue="9080")
  private int port;

  public int getPort() {
      return port;
  }
}

Make sure that if we make any references to the previous class/package name, that it also gets updated.

The deployment exception (for no value set) is as follows:
CWMCG5003E: The [BackedAnnotatedField] @Inject @ConfigProperty private io.openliberty.guides.mpconfig.InventoryConfig.port InjectionPoint dependency was not resolved. Error: java.util.NoSuchElementException: CWMCG0015E: The property port was not found in the configuration.

Update TOC to reflect new guide direction

Update the Table of Contents (TOC) to remove the Dynamic Properties and Data Converters sections.

[Playground] Combining steps 1-4

Allows the user to alter any of the 4 files (java + 3 configs) from steps 1-4, providing any valid key value pairs.

Change the readme to point to the live guide once it is published

Great work! You're done! step

Complete this step by providing a simple one sentence summary of what was learned.

Incorrect grammar on the "Contribute to this guide page"

The sentence on the "contribute to this guide" page uses incorrect grammar - "Is something missing or needs to be fixed?" The subject is "something" and the verb is "is" which makes it "something is missing" and "something is needs" - should be "needing". This is used throughout interactive and static guides.

Review #3

• Change url to not be localhost, change cars-type to car-types, take out port
• Get rid of the WLP setting in server.env
• System props step ordering is unclear because the 4th one is the highest priority when merging
• status bar at bottom of browser saying 'Retrieved data from port '
• add microprofile link in what you'll learn

MP Config: Add in Related Guides link to the static MP Config guide

When we hear that the static MP Config guide is published, add in the link to that guide from our interactive guide.

To do: In microprofile-config-guide.html add the following line:

related-guides: ['microprofile-config']

after the 'duration: 25 minutes' line.

[Step 2] Inject using config File

Add a config file (ordinal = 100) in the application with GetProperties() method with the same key (showing how it's specified) and provide a value (and save). This will override the default value set in the injection.
User will have the java tab in the editor as well, but it will be non-editable.
(Explaining ordinal determination and change detection)

Update description & title for mpConfig

Final:
Title: "Separating configuration from code in microservices"
Description: "Learn how to perform static configuration injection using MicroProfile Config."

Create the Table Of Contents for the new guide

Create the Table Of Contents for the new guide outlining the steps we wish to feature for microprofile-config.

Background Concepts

Config values can be specified as system properties, environment variables, or in configsources. @ConfigProperty qualifier - naming the variable
Default ConfigSources
A Microprofile-Config implementation must provide ConfigSources for the following data out of the
box:
• System properties (default ordinal=400).
• Environment variables (default ordinal=300).
• A ConfigSource for each property if existed under META-INF\microprofile-config.properties

Review #1 of guide. Updates to existing pages.

Updates to existing pages to include

• Title changes
• TOC text changes
• Syntax changes
• Assorted explanation updates.

Add tabbed editor to step 2

Enable mpConfig-1.1 feature in server.xml

Add Readme to github repo

Example: Scenario

Scenario TBD, but a placeholder can be created in the meantime

Feedback #5 to address from playback

Playback review comments from 12/8:

Background Concepts:

• First box in the image: update the text to 'Optional default value'.

Injection step:

• Emphasize that in situations where a property value is REQUIRED by the microservice and no value exists you would get the exception. Other phrases used were 'Where you would want to enforce a value...'. We don't want the design of the API to look bad that an exception is returned. We want to differentiate between optional and mandatory properties.

Website for https://mycarvendor.openliberty.io/car-types:

• Restyle as directed by Design team

Playground:

• Show which file currently has the highest ordinal value using a diagram
• [Erica is working on this] List file from which each property value is being taken. Link selection of the file name to having that file be selected in the tabbed editor.

Overall:

• Consider moving all single editors to be a single file within a tabbed editor to have a consistent look throughout the guide.

[Step 3] Inject using environment variable

Use environment variable (default ordinal = 300) to override the config file ordinal. (using liberty config file)

Rework on the sample application

NOTE: after rewrite, indicate any changes that need to be made to the README for the sample app.

MP Config: Remove the Related Guides link until the static guide is complete.

Remove the link until the static guide is complete and published.

Review #2 of guide. Updates with Dana's comments

List of updates:

• Instead of hiding the browser after run in the editor is clicked, display the browser when the step is showed initially.

• After moving the information presented in the "Using default ConfigSources to provide configuration data" step to background concepts since it did not have any interactive components, move the 'Configuring' steps out a level in the TOC. (Done in #49)

• Re-instate editor slide on 'Providing default values with injection'

• Example step - Text updates to clarify that the port is the configuration property that will be set.

• Injection step - Soften the impact of the error being displayed in bright red

• Default value step - Reword 'anywhere else'. We can now say something like 'in any configuration source for this property' instead since we are now introducing the term 'Config Source' in the Background Concepts.

• Add a 'read-only' indication to editors in the tabbed editor that are there for display purposes only.

• Update TOC labels to "Configuring with an environment variable" and "Configuring with a system property.

• Change 'WebSphere Liberty' to 'Open Liberty' throughout.

• Ensure all filenames are surrounded by <code> tags.

• Other small text changes as noted

Add readme for the sample application

Describe how to download and run the sample application provided in the repo.

[Step 1] Inject config using annotation with default

First the user will inject a config key that doesn't exist and get error.
Then user will add default value and see it getting injected.

Add Relate Guides step

Playground Changes

• split code lines to fit in editor
• change editor filenames
• reword bullet points
• say 'default value' on first bullet
• load property values initially
• require @Inject for properties to be valid
• • add Editor error with button to auto-fix
• • set default to String
• • NOTE: decided the two above are too invasive - requires replacing entire java file content with auto-generated code, overriding user input.
• Implement config_ordinal processing in the playground.
• • Update the instructions to indicate that they can set this value as part of the playground.

File names in editor grow indefinitely

The names of files in editor grow and shrink based on the browser window size (viewport). The problem is that they do not stop growing, so on an ultrawide monitor it renders like the below:

We need to stop growing once we've reached max width of the website (I'm guessing 1200px) and it no longer re-flows, or do something else entirely regarding the text size of the file names.

Change all html files to show car types instead of music

Change Ordinal step needs previous file content

The server.env and bootstrap.properties are empty. They should be filled in with the previous content we had in the previous steps.

ASAP font and other updates

Import the ASAP font into the html of the web browser pages for the MP Config guide.

Tags: Update the tags to include the '@' in front of the syntax tags Inject and ConfigProperty (@Inject and @ConfigProperty)