Skill Level: Beginner

The purpose of this article is provide a simple step by step guide to easily integrate the NewRelic agent into a docker container based in the Liberty image with customization using runtime replacements in the configuration files.


  • Docker configuration knowledge and a Dockerfile based on websphere-liberty image
  • NewRelic account with an enabled license key
  • Template file with Newrelic configuration (newrelic.yml file)


Note: this method can be used to facilitate any change in configuration files during the container start-up.


  1. Prepare NewRelic configuration file template

    Create a directory and store the base configuration template in newrelic.yml file, in our example it’ll be wlp/newrelic.yml . We should add one or more values for replacement, these values should be clearly identified like NEWRELIC_KEY that is the value used in this example.


    Example (This is an extract of the first lines in the example’s configuration):

    common: &default_settings
    # ============================== LICENSE KEY ===============================
    # You must specify the license key associated with your New Relic
    # account. For example, if your license key is 12345 use this:
    # license_key: '12345'
    # The key binds your Agent's data to your account in the New Relic service.
    license_key: 'NEWRELIC_KEY'

    # Agent Enabled
    # Use this setting to disable the agent instead of removing it from the startup command.
    # Default is true.
    agent_enabled: true


  2. Prepare JVM options configuration

    Add a file to configure the JVM options in the Liberty execution environment, it’ll be placed in wlp/jvm.options . We’ll use the same approach of the previous step adding values for runtime replacement, in this case it’ll be NEWRELIC_APP_ENV and we’ll use this one to put the environment’s name in this location.





  3. Prepare a custom liberty configuration

    You can prepare your custom server.xml configuration for Librety server and put the file in wlp/server.xml . You can use the same replacement approach if you need to modify its content based on runtime’s variables.

  4. Adjust your Docker file

    You can adjust your Dockerfile to include these three features


    You’ll need to add one line per replacement, in the following example you’ll see the template value and the name of the system property that will be used “in runtime” to obtain the value in bold. I decided to use the same name as convention to facilitate their identification.

    RUN sed -i '2ised -i -r "s|NEWRELIC_KEY|$NEWRELIC_KEY|g" /opt/newrelic/newrelic.yml' /opt/ibm/helpers/runtime/docker-server.sh
    RUN sed -i '2ised -i -r "s|NEWRELIC_APP_ENV|$NEWRELIC_APP_ENV|g" /config/jvm.options' /opt/ibm/helpers/runtime/docker-server.sh

    Install last Newrelic agent

    This instruction will download and install the last version of the newrelic agent. (Look at the final version of the Dockerfile because you’ll need some addiotional instructions to handle the tools availability and grants)

    RUN curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip && unzip newrelic-java.zip && rm -f newrelic-java.zip

    Prepare customized configuration for Liberty

    The followinfg lines put our application’s WAR file in the image and the custom configuration that we prepared for the Liberty server.

    WORKDIR /opt/ibm/wlp/usr/servers/defaultServer
    COPY application.war ./apps/
    COPY ./wlp/server.xml .


    This is the final version with all the changes integrated and replacements for two variables called NEWRELIC_KEY and NEWRELIC_APP_ENV

    FROM websphere-liberty:javaee7

    USER root
    RUN apt-get update
    RUN apt-get install -y \
    curl \
    COPY ./wlp/jvm.options /config/
    RUN chown 1001:0 /config/jvm.options
    RUN sed -i '2ised -i -r "s|NEWRELIC_KEY|$NEWRELIC_KEY|g" /opt/newrelic/newrelic.yml' /opt/ibm/helpers/runtime/docker-server.sh
    RUN sed -i '2ised -i -r "s|NEWRELIC_APP_ENV|$NEWRELIC_APP_ENV|g" /config/jvm.options' /opt/ibm/helpers/runtime/docker-server.sh
    WORKDIR /opt/
    RUN curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip && unzip newrelic-java.zip && rm -f newrelic-java.zip
    RUN chown -R 1001:0 /opt/newrelic
    RUN chmod -R ag+w /opt/newrelic
    USER 1001

    WORKDIR /opt/ibm/wlp/usr/servers/defaultServer
    COPY application.war ./apps/
    COPY ./wlp/server.xml .
    COPY ./wlp/newrelic.yml /opt/newrelic/
  5. Create the image and use it

    Prepare a text file with the desired values per each environment. In this example i’ll create the file stage.list and the following lines show its content:




    After this you can create the image and start a container using the environment file. The following lines shows how to do it and see the Liberty logs

    docker build -t replacementsExample .
    docker run -d -p 8080:9080 --env-file stage.list --name wlp replacementsExample
    docker exec -ti wlp tail -f /logs/messages.log


    Then you access to the NewRelic panel at https://one.newrelic.com/ and find the details information based on the data captured by your agent.

  6. Conclusion

    This recipe shows an easy integration of Liberty and Newrelic in a docker image with support to customize its settings based on the runtime environment and using a content replacement approach. Is real that Newrelic can be customized with java options only but the purpose of the document exceeds this product and shows that this method can be used for other situations with a higher configuration complexity or linked to other products with less customization capabilities.

Join The Discussion