From 25066b8fc3277d8ad84152aeeb4064a0eddeb046 Mon Sep 17 00:00:00 2001 From: Justine Chen Date: Wed, 27 Feb 2019 08:26:00 -0800 Subject: [PATCH] Multipane (#32) * Converting to multipane * Dockerfile file name * Updated hotspsots/ includes * Minor updates for multipane, dockerfile hotspot not working * Fixing hotspot liness * Updated commands and inline hotspots, Dockerfile is not being picked up by hotspots * Updating action to create dockerfile * Added text to include Dockerfile * Updated wording * Updated multipane * Updated multipane * Updated multipane * Updated multipane * Updated arrow to hotspot when telling users to read the guide * Updated README * Formatted pom.xml to 90 chars per line * Parent POM update * Updated start/pom.xml to match finish/ * Changed wording in readme * Updated read me and hotspots * Updated pom and readme * README and pom update * Updates to pom and to start pom * Testing * Testing * Testing * Updated readme based on Rachel's feedback * Removed testing * Removed testing * Updated hotspots * Updated hyperlinks * Updated image version, output and made docker stop into a command * Added hyperlink * README hotspot changes * Updated readme * Added hotspots and updated mvn package command * Reverted back to parent pom.xml * README update * README update * README update * README update - removed comment in right panel * Changed hotspot from properties to @Path * 2nd round * Updated pom.xml and README * Removed finish.adoc include from README.adoc * Trying to test docker commands and endpoint * Trying to test docker commands and endpoint * Trying to test docker commands and endpoint * Trying to test docker commands and endpoint * Trying to test docker commands and endpoint * Trying to test docker commands and endpoint * Trying to test docker commands * Trying to add docker commands in travis * Updating order of dependencies * JDK 11 pom update * jdk update * Updated README * README update with edit action arrow * Updated README * Update README * Updated README * Updated README with [hotspot] changes * Updated README with link in new tab changes * Updated README with link in new tab changes * Updated README * Updated README.adoc * Updated README.adoc * Fix the .dockerignore tab name and the hotspot pom.xml is referencing * Updating phrasing to be more consistent * Update arrows should not highlight code * Change the guide attribution to point to master --- .travis.yml | 10 ++- README.adoc | 222 +++++++++++++++++++++++++++---------------------- finish/pom.xml | 44 +++++++--- start/pom.xml | 56 ++++++++----- 4 files changed, 198 insertions(+), 134 deletions(-) diff --git a/.travis.yml b/.travis.yml index 94ac38c..d280443 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,9 +1,17 @@ language: java +services: +- docker before_script: - unset _JAVA_OPTIONS - cd finish script: -- mvn clean install +- mvn -q clean install +- docker build -t ol-runtime . +- docker run -d --name rest-app -p 9080:9080 -p 9443:9443 -v /home/travis/build/OpenLiberty/guide-docker/finish/target/liberty/wlp/usr/servers:/servers ol-runtime +- sleep 60 +- status="$(curl --write-out "%{http_code}\n" --silent --output /dev/null "http://localhost:9080/LibertyProject/System/properties")"; if [ "$status" == "200" ]; then echo ENDPOINT OK; else echo "$status"; echo ENDPOINT NOT OK; exit 1; fi; +- docker stop rest-app +- docker rm rest-app - serverName=$(target/liberty/wlp/bin/server list | cut -d '.' -f2| tr -d '\n'); - build=$(grep "Open Liberty" target/liberty/wlp/usr/servers/"$serverName"/logs/console.log | cut -d' ' -f5 | cut -d')' -f1 ); release=$( echo "$build" | cut -d'/' -f1); number=$( diff --git a/README.adoc b/README.adoc index 8d616a6..b621807 100644 --- a/README.adoc +++ b/README.adoc @@ -6,9 +6,9 @@ // Contributors: // IBM Corporation :projectid: docker -:page-layout: guide +:page-layout: guide-multipane :page-duration: 20 minutes -:page-description: Learn how to containerize a microservice with Docker for iterative development +:page-description: Learn how to containerize a microservice with Docker for iterative development. :page-releasedate: 2017-12-27 :page-tags: ['Docker'] :page-related-guides: ['rest-intro'] @@ -18,6 +18,7 @@ :page-permalink: /guides/{projectid} :common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/master :source-highlighter: prettify +:guide-author: Open Liberty = Using Docker containers to develop microservices [.hidden] @@ -33,9 +34,9 @@ Learn how to containerize a microservice with Docker for iterative development You will learn how to run and continuously develop a simple REST application with Open Liberty and Docker. -The REST application that you will run was written for you in advance and can be found in the +The implementation of the REST application can be found in the `start/src` directory. To learn more about this application and how to build it, read -https://openliberty.io/guides/rest-intro.html[Creating a RESTful web service]. +https://openliberty.io/guides/rest-intro.html[Creating a RESTful web service^]. To containerize your application, first build it with Maven and add it to the servers of your choice. Second, create a Docker image that contains an Open Liberty runtime. Third, run this image @@ -49,9 +50,9 @@ can think of Docker like a virtual machine that runs various applications. Howev machine, you can run these applications simultaneously on a single system and independent of one another. -Learn more about Docker on the official Docker page: https://www.docker.com/what-docker +Learn more about Docker on the https://www.docker.com/what-docker[official Docker page^]. -Learn how to install Docker on the official instructions page: https://docs.docker.com/engine/installation +Learn how to install Docker on the https://docs.docker.com/engine/installation[official instructions page^]. === What is a container? @@ -60,7 +61,7 @@ with the entire environment that it needs to run. Containers are small compared run on any environment where Docker is set up. Moreover, you can run multiple containers on a single machine at the same time in isolation from each other. -Learn more about containers on the official Docker page: https://www.docker.com/what-container +Learn more about containers on the https://www.docker.com/what-container[official Docker page^]. === Why use containers? @@ -82,10 +83,9 @@ and they take up only a fraction of the memory of a single image. // ================================================================================================= // Getting Started // ================================================================================================= - +[role='command'] include::{common-includes}/gitclone.adoc[] - // ================================================================================================= // Building your application // ================================================================================================= @@ -93,37 +93,23 @@ include::{common-includes}/gitclone.adoc[] == Building your application Before you begin, build your application. To do this, navigate to the `start` directory and run the Maven -`clean` and `install` goals: +`install` goal: ----- -mvn clean install ----- +[role='command'] +``` +mvn install +``` + +Your [hotspot]`pom.xml` file is already configured to add your REST application to the `defaultServer`. But you can tweak this configuration or add your own for another server by updating the [hotspot=181-192]`` element. -Your `pom.xml` file is already configured to add your REST application to the `defaultServer` server, -but you can tweak this configuration or add your own for another server: +Learn more about this goal on the official https://github.com/WASdev/ci.maven/blob/master/docs/install-apps.md[Maven Liberty plug-in repository^]. -[source, xml, indent=0] +pom.xml +[source, xml, linenums, role="code_column"] ---- - - - install-app - package - - install-apps - - - apps - true - project - - +include::finish/pom.xml[tags=**] ---- -The `install-apps` goal copies the application into the specified directory of the specified server. -In this case, the goal copies the `rest.war` file into the `apps` directory of the `defaultServer` server. - -Learn more about this goal on the official https://github.com/WASdev/ci.maven/blob/master/docs/install-apps.md[Maven Liberty plug-in repository]. - // ================================================================================================= // Creating the Dockerfile // ================================================================================================= @@ -135,30 +121,40 @@ container. Every Dockerfile begins with a parent or base image on top of which v are run. For example, you can start your image from scratch and execute commands that download and install Java, or you can start from an image that already contains a Java installation. -Create a regular `start/Dockerfile` file: +Navigate to the `start` directory to begin. -[source, indent=0] +[role="code_command hotspot",subs="quotes"] ---- -include::finish/Dockerfile[tags=**] +#Create the `Dockerfile`.# +`Dockerfile` ---- -The `FROM` instruction initializes a new build stage and indicates the parent image from which your +The [hotspot=2 file=0]`FROM` instruction initializes a new build stage and indicates the parent image from which your image is built. If you don't need a parent image, then use `FROM scratch`, which makes your image a -base image. In this case, you're using the `openliberty/open-liberty:javaee7` image as your parent +base image. + +In this case, you're using the `openliberty/open-liberty:javaee8` image as your parent image, which comes with the latest Open Liberty runtime. -The `RUN` instruction executes various shell commands in a new layer on top of the current image. + +The [hotspot=5 file=0]`RUN` instruction executes various shell commands in a new layer on top of the current image. In this case, you create a symlink between the `/opt/ol/wlp/usr/servers` directory and the `/servers` directory. This way, you can mount your servers more easily because you don't need to use long path names. -The `CMD` and `ENTRYPOINT` instructions define a default command that executes when the image runs as -a container. These two instructions function the same way, except that the `CMD` instruction is overridden +The [hotspot=8 file=0]`ENTRYPOINT` and [hotspot=9]`CMD` instructions define a default command that executes when the image runs as +a container. These two instructions function the same way, except that the [hotspot=9 file=0]`CMD` instruction is overridden with any arguments that are passed at the end of the `docker run` command. In contrast, the -`ENTRYPOINT` instruction requires the `--entrypoint` flag to be overridden. In this case, you use -the `ENTRYPOINT` instruction to start an Open Liberty server and the `CMD` instruction to indicate -which server to start. Because the `CMD` instruction is easily overridden, starting any server is convenient. +[hotspot=8 file=0]`ENTRYPOINT` instruction requires the `--entrypoint` flag to be overridden. In this case, you use +the [hotspot=8 file=0]`ENTRYPOINT` instruction to start an Open Liberty server and the [hotspot=9 file=0]`CMD` instruction to indicate +which server to start. Because the [hotspot=9 file=0]`CMD` instruction is easily overridden, starting any server is convenient. + +For a complete list of available instructions, see the https://docs.docker.com/engine/reference/builder[Docker documentation^]. -For a complete list of available instructions, see the https://docs.docker.com/engine/reference/builder[Docker documentation]. +Dockerfile +[source, text, linenums, role="code_column"] +---- +include::finish/Dockerfile[tags=**] +---- === Optional: Writing a .dockerignore file @@ -167,10 +163,20 @@ as the Dockerfile to its build context, making them available for use in instruc To make image building faster, add all files and directories that aren't necessary for building your image to a `.dockerignore` file. This excludes them from the build context. -A `.dockerignore` file is available to you in the `start` directory. This file includes the `src` -directory, the `pom.xml` file, and some system files. Feel free to add anything else that you want to exclude +A [hotspot file=0]`.dockerignore` file is available to you in the `start` directory. This file includes the [hotspot=2 file=0]`src` +directory, the [hotspot file=1]`pom.xml` file, and some system files. Feel free to add anything else that you want to exclude. +`.dockerignore` +[source, text, linenums, role="code_column"] +---- +include::finish/.dockerignore[tags=**] +---- +pom.xml +[source, xml, linenums, role="code_column"] +---- +include::finish/pom.xml[tags=**] +---- // ================================================================================================= // Building the image // ================================================================================================= @@ -181,7 +187,7 @@ To build your image, make sure that your Docker daemon is running and execute th from the command line. If you execute your build from the same directory as your Dockerfile, you can use the period character (`.`) notation to specify the location for the build context. Otherwise, use the `-f` flag to point to your Dockerfile: - +[role='command'] ``` docker build -t ol-runtime . ``` @@ -195,43 +201,40 @@ If your build runs successfully, you'll see an output similar to the following: [role="no_copy"] ---- -Sending build context to Docker daemon 3.072kB -Step 1/4 : FROM openliberty/open-liberty:javaee7 -javaee7: Pulling from openliberty/open-liberty -660c48dd555d: Pull complete -4c7380416e78: Pull complete -421e436b5f80: Pull complete -e4ce6c3651b3: Pull complete -be588e74bd34: Pull complete -6da4611cbdb3: Pull complete -3cbd5728a38e: Pull complete -38f12bc85354: Pull complete -540c270bda6a: Pull complete -bbd56d34f762: Pull complete -8f181e95aa97: Pull complete -4c14e095e68e: Pull complete -bed46b62b8c3: Pull complete -Digest: sha256:d6793b7865d86ad43e5cc7c02089f7eefd2b1af3e312bc453e4779f4f24c28a6 -Status: Downloaded newer image for openliberty/open-liberty:javaee7 - ---> d71303f77e8d +Sending build context to Docker daemon 148.9MB +Step 1/4 : FROM open-liberty +latest: Pulling from library/open-liberty +7b8b6451c85f: Pull complete +ab4d1096d9ba: Pull complete +e6797d1788ac: Pull complete +e25c5c290bde: Pull complete +27b2fbbc72b1: Pull complete +aa35dfd74487: Pull complete +1ade56d64661: Pull complete +3493ef172f60: Pull complete +cd6dff6d245d: Pull complete +82450af30afc: Pull complete +Digest: sha256:b7576e4278030537765d4185c4641ee2769194226263f979109ed4fa0e1aa4e4 +Status: Downloaded newer image for open-liberty:latest + ---> 45d4b67ace5b Step 2/4 : RUN ln -s /opt/ol/wlp/usr/servers /servers - ---> Running in 191078d2ce16 - ---> dfef8073fe42 -Removing intermediate container 191078d2ce16 -Step 3/4 : ENTRYPOINT /opt/ol/wlp/bin/server run - ---> Running in 38e48bae6dd7 - ---> 1015cbcdcf37 -Removing intermediate container 38e48bae6dd7 -Step 4/4 : CMD defaultServer - ---> Running in 3fea454efdcd - ---> ee99661593eb -Removing intermediate container 3fea454efdcd -Successfully built ee99661593eb + ---> Running in cbeb275770ab +Removing intermediate container cbeb275770ab + ---> 937183f8460b +Step 3/4 : ENTRYPOINT ["/opt/ol/wlp/bin/server", "run"] + ---> Running in 856a4bdec82b +Removing intermediate container 856a4bdec82b + ---> 6cf732381877 +Step 4/4 : CMD ["defaultServer"] + ---> Running in 1a543a9e37d8 +Removing intermediate container 1a543a9e37d8 + ---> 8fdcad065d25 +Successfully built 8fdcad065d25 Successfully tagged ol-runtime:latest ---- Each step of the build has a unique ID, which represents the ID of an intermediate image. For example, step 2 -has the ID `dfef8073fe42`, and step 4 has the ID `ee99661593eb`, which is also the ID of the final image. +has the ID `937183f8460b`, and step 4 has the ID `8fdcad065d25`, which is also the ID of the final image. During the first build of your image, Docker caches every new layer as a separate image and reuses them for future builds for layers that didn't change. For example, if you run the build again, Docker reuses the images that it cached for steps 2 - 4. However, if you make a change in your Dockerfile, Docker would @@ -240,11 +243,12 @@ need to rebuild the subsequent layer since this layer also changed. However, you can also completely disable the caching of intermediate layers by running the build with the `--no-cache=true` flag: +[role='command'] ``` docker build -t ol-runtime --no-cache=true . ``` -Learn more about the image build process on the https://docs.docker.com/engine/reference/commandline/image_build[Docker documentation]. +Learn more about the image build process on the https://docs.docker.com/engine/reference/commandline/image_build[Docker documentation^]. // ================================================================================================= @@ -253,14 +257,15 @@ Learn more about the image build process on the https://docs.docker.com/engine/r == Containerize your application -Now that your image is built, execute the Docker `run` command from the command line to run it: +Now that your image is built, execute the Docker `run` command with the absolute path to this guide: +[role='command'] ``` docker run -d --name rest-app -p 9080:9080 -p 9443:9443 -v /start/target/liberty/wlp/usr/servers:/servers ol-runtime ``` Alternatively, you can also execute the `run` command to mount a single server instead of the whole `servers` directory: - +[role='command'] ``` docker run -d --name rest-app -p 9080:9080 -p 9443:9443 -v /start/target/liberty/wlp/usr/servers/defaultServer:/servers/defaultServer ol-runtime ``` @@ -272,7 +277,7 @@ Let's break down the flags: | *Flag* | *Description* | -d | This flag tells Docker to run the container in the background. Without this flag, Docker runs the container in the foreground. -| --name | This flag gives the container a name. +| --name | This flag specifies a name for the container. | -p | This flag maps the container ports to the host ports. | -v | This flag mounts a directory or file to the file system of the container. |=== @@ -281,11 +286,12 @@ You can pass in an optional server name at the end of the `run` command to overr server in the `CMD` instruction. For example, if your `servers` directory also contains a server called `testServer`, then it can be started as shown in the following example: +[role='no_copy'] ``` docker run -d --name rest-app -p 9080:9080 -p 9443:9443 -v /start/target/liberty/wlp/usr/servers:/servers ol-runtime testServer ``` -Learn more about running containers on the official Docker page: https://docs.docker.com/engine/reference/run +Learn more about running containers on the https://docs.docker.com/engine/reference/run[official Docker page^] // ================================================================================================= // Testing the container @@ -305,25 +311,32 @@ CONTAINER ID IMAGE CREATED STATUS To view a full list of all available containers, run the `docker ps -a` command from the command line. -If your container is running without problems, point your browser to `http://localhost:9080/LibertyProject/System/properties`, +If your container is running without problems, point your browser to http://localhost:9080/LibertyProject/System/properties[http://localhost:9080/LibertyProject/System/properties^], where you can see a JSON file that contains the system properties of the JVM in your container. - -Edit the `src/main/java/io/openliberty/guides/rest/PropertiesResource.java` class and change the `@Path` -annotation to `"properties-new"`. These edits change the endpoint of your application from `/properties` to `/properties-new`: - -[source, Java, indent=0] +[role="code_command hotspot", subs="quotes"] ---- -@Path("properties-new") -public class PropertiesResource { - ... -} +#Update the `PropertiesResource` class.# +`src/main/java/io/openliberty/guides/rest/PropertiesResource.java` ---- -To see these changes reflected in the container, run the `mvn package` command from the command line to -rebuild your application and point your browser to `http://localhost:9080/LibertyProject/System/properties-new`. +[role="edit_command_text"] +Change the endpoint of your application from `properties` to `properties-new` by changing the [hotspot=18]`@Path` +annotation to `"properties-new"`. + + +To see these changes reflected in the container, run the following command from the command line to +rebuild your application and point your browser to http://localhost:9080/LibertyProject/System/properties-new[http://localhost:9080/LibertyProject/System/properties-new^]. +[role='command'] +``` +mvn package +``` You see the same JSON file that you saw previously. -To stop your container, run the `docker stop rest-app` command from the command line. +To stop your container, run the following command from the command line. +[role='command'] +``` +docker stop rest-app +``` If a problem occurs and your container exits prematurely, the container won't appear in the container list that the `docker ps` command displays. Instead, your container appears with an `Exited` @@ -332,10 +345,17 @@ container logs for any potential problems and double-check that your Dockerfile find the cause of the issue, remove the faulty container with the `docker rm rest-app` command, rebuild your image, and start the container again. +PropertiesResource.java +[source, Java, linenums, role="code_column"] +---- +include::finish/src/main/java/io/openliberty/guides/rest/PropertiesResource.java[tags=**;!comment] +---- + == Great work! You're done! -You containerized a simple REST application. You can now continuously deliver changes to the application, +You containerized a simple REST application in Open Liberty. You can now continuously deliver changes to the application, and they will reflect automatically when the application rebuilds. -include::{common-includes}/finish.adoc[] + +include::{common-includes}/attribution.adoc[subs="attributes"] diff --git a/finish/pom.xml b/finish/pom.xml index abccffc..131af4c 100644 --- a/finish/pom.xml +++ b/finish/pom.xml @@ -1,5 +1,8 @@ - + 4.0.0 @@ -34,6 +37,18 @@ + + io.openliberty.features + jaxrs-2.1 + esa + provided + + + io.openliberty.features + jsonp-1.1 + esa + provided + junit junit @@ -43,13 +58,13 @@ org.apache.cxf cxf-rt-rs-client - 3.1.11 + 3.2.6 test org.apache.cxf cxf-rt-rs-extension-providers - 3.1.11 + 3.2.6 test @@ -70,20 +85,21 @@ esa provided + javax.xml.bind jaxb-api - 2.2.11 + 2.3.1 com.sun.xml.bind jaxb-core - 2.2.11 + 2.3.0.1 com.sun.xml.bind jaxb-impl - 2.2.11 + 2.3.2 javax.activation @@ -116,7 +132,9 @@ **/it/** - ${project.build.directory}/test-reports/unit + + ${project.build.directory}/test-reports/unit + @@ -206,7 +224,9 @@ **/it/** - ${testServerHttpPort} + + ${testServerHttpPort} + ${warContext} @@ -219,8 +239,12 @@ - ${project.build.directory}/test-reports/it/failsafe-summary.xml - ${project.build.directory}/test-reports/it + + ${project.build.directory}/test-reports/it/failsafe-summary.xml + + + ${project.build.directory}/test-reports/it + diff --git a/start/pom.xml b/start/pom.xml index abccffc..b5fb882 100644 --- a/start/pom.xml +++ b/start/pom.xml @@ -1,5 +1,8 @@ - + 4.0.0 @@ -34,6 +37,18 @@ + + io.openliberty.features + jaxrs-2.1 + esa + provided + + + io.openliberty.features + jsonp-1.1 + esa + provided + junit junit @@ -43,13 +58,13 @@ org.apache.cxf cxf-rt-rs-client - 3.1.11 + 3.2.6 test org.apache.cxf cxf-rt-rs-extension-providers - 3.1.11 + 3.2.6 test @@ -58,32 +73,21 @@ 1.0.4 test - - io.openliberty.features - jaxrs-2.1 - esa - provided - - - io.openliberty.features - jsonp-1.1 - esa - provided - + javax.xml.bind jaxb-api - 2.2.11 + 2.3.1 com.sun.xml.bind jaxb-core - 2.2.11 + 2.3.0.1 com.sun.xml.bind jaxb-impl - 2.2.11 + 2.3.2 javax.activation @@ -116,7 +120,9 @@ **/it/** - ${project.build.directory}/test-reports/unit + + ${project.build.directory}/test-reports/unit + @@ -206,7 +212,9 @@ **/it/** - ${testServerHttpPort} + + ${testServerHttpPort} + ${warContext} @@ -219,8 +227,12 @@ - ${project.build.directory}/test-reports/it/failsafe-summary.xml - ${project.build.directory}/test-reports/it + + ${project.build.directory}/test-reports/it/failsafe-summary.xml + + + ${project.build.directory}/test-reports/it +