git clone https://github.com/openliberty/guide-getting-started.git
cd guide-getting-started
Contents
- What you’ll learn
- Getting started
- Building and running the application
- Starting and stopping Open Liberty in the background
- Updating Liberty’s configuration without restarting
- Updating the source code without restarting Liberty
- Checking the Open Liberty logs
- Running the application in a Docker container
- Developing the application in a Docker container
- Running the application from a minimal runnable JAR
- Great work! You’re done!
- Guide Attribution
Tags
Getting started with Open Liberty
Prerequisites:
Learn how to develop a Java application on Open Liberty with Maven and Docker.
What you’ll learn
You will learn how to run and update a simple REST microservice on Open Liberty. You will use Maven throughout the guide to build and deploy the microservice as well as to interact with the running Liberty instance.
Open Liberty is an open application framework designed for the cloud. It’s small, lightweight, and designed with modern cloud-native application development in mind. It supports the full MicroProfile and Jakarta EE APIs and is composable, meaning that you can use only the features that you need, keeping everything lightweight, which is great for microservices. It also deploys to every major cloud platform, including Docker, Kubernetes, and Cloud Foundry.
Maven is an automation build tool that provides an efficient way to develop Java applications. Using Maven, you will build a simple microservice, called system
, that collects basic system properties from your laptop and displays them on an endpoint that you can access in your web browser.
You’ll also explore how to package your application with Open Liberty so that it can be deployed anywhere in one go. You will then make Liberty configuration and code changes and see how they are immediately picked up by a running instance.
Finally, you will package the application along with Liberty’s configuration into a Docker image and run that image as a container.
Getting started
The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:
The start
directory contains the starting project that you will build upon.
The finish
directory contains the finished project that you will build.
Before you begin, make sure you have all the necessary prerequisites.
You have cloned a Maven project. To learn how to create a Liberty Maven project from scratch and edit your application using the Liberty Tools, see Developing a cloud-native Java application with Liberty Tools in IntelliJ IDEA.
Building and running the application
Your application is configured to be built with Maven. Every Maven-configured project contains a pom.xml
file, which defines the project configuration, dependencies, plug-ins, and so on.
Your pom.xml
file is located in the start
directory and is configured to include the liberty-maven-plugin
, which allows you to install applications into Open Liberty and manage the associated Liberty instances.
pom.xml
1<?xml version='1.0' encoding='utf-8'?>
2<project xmlns="http://maven.apache.org/POM/4.0.0"
3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5 <modelVersion>4.0.0</modelVersion>
6
7 <groupId>io.openliberty.guides</groupId>
8 <artifactId>guide-getting-started</artifactId>
9 <version>1.0-SNAPSHOT</version>
10 <packaging>war</packaging>
11
12 <properties>
13 <maven.compiler.source>11</maven.compiler.source>
14 <maven.compiler.target>11</maven.compiler.target>
15 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16 <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
17 <!-- Liberty configuration -->
18 <liberty.var.http.port>9080</liberty.var.http.port>
19 <liberty.var.https.port>9443</liberty.var.https.port>
20 </properties>
21
22 <dependencies>
23 <!-- Provided dependencies -->
24 <dependency>
25 <groupId>jakarta.platform</groupId>
26 <artifactId>jakarta.jakartaee-api</artifactId>
27 <version>10.0.0</version>
28 <scope>provided</scope>
29 </dependency>
30 <dependency>
31 <groupId>org.eclipse.microprofile</groupId>
32 <artifactId>microprofile</artifactId>
33 <version>6.1</version>
34 <type>pom</type>
35 <scope>provided</scope>
36 </dependency>
37 <!-- For tests -->
38 <dependency>
39 <groupId>org.junit.jupiter</groupId>
40 <artifactId>junit-jupiter</artifactId>
41 <version>5.11.1</version>
42 <scope>test</scope>
43 </dependency>
44 <dependency>
45 <groupId>org.jboss.resteasy</groupId>
46 <artifactId>resteasy-client</artifactId>
47 <version>6.2.10.Final</version>
48 <scope>test</scope>
49 </dependency>
50 <dependency>
51 <groupId>org.jboss.resteasy</groupId>
52 <artifactId>resteasy-json-binding-provider</artifactId>
53 <version>6.2.10.Final</version>
54 <scope>test</scope>
55 </dependency>
56 <dependency>
57 <groupId>org.glassfish</groupId>
58 <artifactId>jakarta.json</artifactId>
59 <version>2.0.1</version>
60 <scope>test</scope>
61 </dependency>
62 </dependencies>
63
64 <build>
65 <finalName>${project.artifactId}</finalName>
66 <plugins>
67 <!-- Enable liberty-maven plugin -->
68 <!-- tag::libertyMavenPlugin[] -->
69 <plugin>
70 <groupId>io.openliberty.tools</groupId>
71 <artifactId>liberty-maven-plugin</artifactId>
72 <version>3.10.3</version>
73 </plugin>
74 <!-- end::libertyMavenPlugin[] -->
75 <plugin>
76 <groupId>org.apache.maven.plugins</groupId>
77 <artifactId>maven-war-plugin</artifactId>
78 <version>3.4.0</version>
79 </plugin>
80 <plugin>
81 <groupId>org.apache.maven.plugins</groupId>
82 <artifactId>maven-surefire-plugin</artifactId>
83 <version>3.5.0</version>
84 </plugin>
85 <!-- Plugin to run functional tests -->
86 <!-- tag::maven-failsafe-plugin[] -->
87 <plugin>
88 <groupId>org.apache.maven.plugins</groupId>
89 <artifactId>maven-failsafe-plugin</artifactId>
90 <version>3.5.0</version>
91 <configuration>
92 <systemPropertyVariables>
93 <http.port>${liberty.var.http.port}</http.port>
94 <!-- tag::contextRoot[] -->
95 <context.root>/dev</context.root>
96 <!-- end::contextRoot[] -->
97 </systemPropertyVariables>
98 </configuration>
99 </plugin>
100 <!-- end::maven-failsafe-plugin[] -->
101 </plugins>
102 </build>
103</project>
To begin, navigate to the start
directory. Build the system
microservice that is provided and deploy it to Open Liberty by running the Maven liberty:run
goal:
cd start
mvn liberty:run
The mvn
command initiates a Maven build, during which the target
directory is created to store all build-related files.
The liberty:run
argument specifies the Open Liberty run
goal, which starts an Open Liberty instance in the foreground. As part of this phase, an Open Liberty runtime is downloaded and installed into the target/liberty/wlp
directory, an instance of Liberty is created and configured in the target/liberty/wlp/usr/servers/defaultServer
directory, and the application is installed into that instance using loose config.
For more information about the Liberty Maven plug-in, see its GitHub repository.
When the Liberty instance begins starting up, various messages display in your command-line session. Wait for the following message, which indicates that Liberty’s startup is complete:
[INFO] [AUDIT] CWWKF0011I: The server defaultServer is ready to run a smarter planet.
To access the system
microservice, see the http://localhost:9080/system/properties URL, and you see a list of the various system properties of your JVM:
{
"os.name": "Mac OS X",
"java.version": "1.8.0_151",
...
}
When you need to stop the Liberty instance, press CTRL+C
in the command-line session where you ran Liberty, or run the liberty:stop
goal from the start
directory in another command-line session:
mvn liberty:stop
Starting and stopping Open Liberty in the background
Although you can start and stop Liberty in the foreground by using the Maven liberty:run
goal, you can also start and stop the Liberty instance in the background with the Maven liberty:start
and liberty:stop
goals:
mvn liberty:start mvn liberty:stop
Updating Liberty’s configuration without restarting
The Open Liberty Maven plug-in includes a dev
goal that listens for any changes in the project, including application source code or configuration. The Open Liberty instance automatically reloads the configuration without restarting. This goal allows for quicker turnarounds and an improved developer experience.
Stop the Open Liberty instance if it is running, and start it in dev mode by running the liberty:dev
goal in the start
directory:
mvn liberty:dev
Dev mode automatically picks up changes that you make to your application and allows you to run tests by pressing the enter/return
key in the active command-line session. When you’re working on your application, rather than rerunning Maven commands, press the enter/return
key to verify your change.
As before, you can see that the application is running by going to the http://localhost:9080/system/properties URL.
Now try updating Liberty’s server.xml
configuration file while the instance is running in dev mode. The system
microservice does not currently include health monitoring to report whether the Liberty instance and the microservice that it runs are healthy. You can add health reports with the MicroProfile Health feature, which adds a /health
endpoint to your application. If you try to access this endpoint now at the http://localhost:9080/health/ URL, you see a 404 error because the /health
endpoint does not yet exist:
Error 404: java.io.FileNotFoundException: SRVE0190E: File not found: /health
To add the MicroProfile Health feature to the Liberty instance, include the mpHealth
feature in the server.xml
.
Replace the Libertyserver.xml
configuration file.src/main/liberty/config/server.xml
server.xml
After you make the file changes, Open Liberty automatically reloads its configuration. When enabled, the mpHealth
feature automatically adds a /health
endpoint to the application. You can see the instance being updated in the Liberty log displayed in your command-line session:
[INFO] [AUDIT] CWWKG0016I: Starting server configuration update.
[INFO] [AUDIT] CWWKT0017I: Web application removed (default_host): http://foo:9080/
[INFO] [AUDIT] CWWKZ0009I: The application io.openliberty.guides.getting-started has stopped successfully.
[INFO] [AUDIT] CWWKG0017I: The server configuration was successfully updated in 0.284 seconds.
[INFO] [AUDIT] CWWKT0016I: Web application available (default_host): http://foo:9080/health/
[INFO] [AUDIT] CWWKF0012I: The server installed the following features: [mpHealth-4.0].
[INFO] [AUDIT] CWWKF0008I: Feature update completed in 0.285 seconds.
[INFO] [AUDIT] CWWKT0016I: Web application available (default_host): http://foo:9080/
[INFO] [AUDIT] CWWKZ0003I: The application io.openliberty.guides.getting-started updated in 0.173 seconds.
Try to access the /health
endpoint again by visiting the http://localhost:9080/health URL. You see the following JSON:
{
"checks":[],
"status":"UP"
}
Now you can verify whether your Liberty instance is up and running.
Updating the source code without restarting Liberty
The RESTful application that contains your system
microservice runs in a Liberty instance from its .class
file and other artifacts. Open Liberty automatically monitors these artifacts, and whenever they are updated, it updates the running instance without the need for the instance to be restarted.
Look at your pom.xml
file.
pom.xml
1<?xml version='1.0' encoding='utf-8'?>
2<project xmlns="http://maven.apache.org/POM/4.0.0"
3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5 <modelVersion>4.0.0</modelVersion>
6
7 <groupId>io.openliberty.guides</groupId>
8 <artifactId>guide-getting-started</artifactId>
9 <version>1.0-SNAPSHOT</version>
10 <packaging>war</packaging>
11
12 <properties>
13 <maven.compiler.source>11</maven.compiler.source>
14 <maven.compiler.target>11</maven.compiler.target>
15 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16 <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
17 <!-- Liberty configuration -->
18 <liberty.var.http.port>9080</liberty.var.http.port>
19 <liberty.var.https.port>9443</liberty.var.https.port>
20 </properties>
21
22 <dependencies>
23 <!-- Provided dependencies -->
24 <dependency>
25 <groupId>jakarta.platform</groupId>
26 <artifactId>jakarta.jakartaee-api</artifactId>
27 <version>10.0.0</version>
28 <scope>provided</scope>
29 </dependency>
30 <dependency>
31 <groupId>org.eclipse.microprofile</groupId>
32 <artifactId>microprofile</artifactId>
33 <version>6.1</version>
34 <type>pom</type>
35 <scope>provided</scope>
36 </dependency>
37 <!-- For tests -->
38 <dependency>
39 <groupId>org.junit.jupiter</groupId>
40 <artifactId>junit-jupiter</artifactId>
41 <version>5.11.1</version>
42 <scope>test</scope>
43 </dependency>
44 <dependency>
45 <groupId>org.jboss.resteasy</groupId>
46 <artifactId>resteasy-client</artifactId>
47 <version>6.2.10.Final</version>
48 <scope>test</scope>
49 </dependency>
50 <dependency>
51 <groupId>org.jboss.resteasy</groupId>
52 <artifactId>resteasy-json-binding-provider</artifactId>
53 <version>6.2.10.Final</version>
54 <scope>test</scope>
55 </dependency>
56 <dependency>
57 <groupId>org.glassfish</groupId>
58 <artifactId>jakarta.json</artifactId>
59 <version>2.0.1</version>
60 <scope>test</scope>
61 </dependency>
62 </dependencies>
63
64 <build>
65 <finalName>${project.artifactId}</finalName>
66 <plugins>
67 <!-- Enable liberty-maven plugin -->
68 <plugin>
69 <groupId>io.openliberty.tools</groupId>
70 <artifactId>liberty-maven-plugin</artifactId>
71 <version>3.10.3</version>
72 </plugin>
73 <plugin>
74 <groupId>org.apache.maven.plugins</groupId>
75 <artifactId>maven-war-plugin</artifactId>
76 <version>3.4.0</version>
77 </plugin>
78 <plugin>
79 <groupId>org.apache.maven.plugins</groupId>
80 <artifactId>maven-surefire-plugin</artifactId>
81 <version>3.5.0</version>
82 </plugin>
83 <!-- Plugin to run functional tests -->
84 <plugin>
85 <groupId>org.apache.maven.plugins</groupId>
86 <artifactId>maven-failsafe-plugin</artifactId>
87 <version>3.5.0</version>
88 <configuration>
89 <systemPropertyVariables>
90 <http.port>${liberty.var.http.port}</http.port>
91 <context.root>/dev</context.root>
92 </systemPropertyVariables>
93 </configuration>
94 </plugin>
95 </plugins>
96 </build>
97</project>
Try updating the source code while Liberty is running in dev mode. At the moment, the /health
endpoint reports whether the Liberty instance is running, but the endpoint doesn’t provide any details on the microservices that are running inside of the instance.
MicroProfile Health offers health checks for both readiness and liveness. A readiness check allows third-party services, such as Kubernetes, to know if the microservice is ready to process requests. A liveness check allows third-party services to determine if the microservice is running.
Create theSystemReadinessCheck
class.src/main/java/io/openliberty/sample/system/SystemReadinessCheck.java
SystemReadinessCheck.java
The SystemReadinessCheck
class verifies that the
system
microservice is not in maintenance by checking a config property.
Create theSystemLivenessCheck
class.src/main/java/io/openliberty/sample/system/SystemLivenessCheck.java
SystemLivenessCheck.java
The SystemLivenessCheck
class reports a status of
DOWN
if the microservice uses over 90% of the maximum amount of memory.
After you make the file changes, Open Liberty automatically reloads its configuration and the system
application.
The following messages display in your first command-line session:
[INFO] [AUDIT] CWWKT0017I: Web application removed (default_host): http://foo:9080/
[INFO] [AUDIT] CWWKZ0009I: The application io.openliberty.guides.getting-started has stopped successfully.
[INFO] [AUDIT] CWWKT0016I: Web application available (default_host): http://foo:9080/
[INFO] [AUDIT] CWWKZ0003I: The application io.openliberty.guides.getting-started updated in 0.136 seconds.
Access the /health
endpoint again by going to the http://localhost:9080/health URL. This time you see the overall status of your Liberty instance and the aggregated data of the liveness and readiness checks for the system
microservice:
{
"checks":[
{
"data":{},
"name":"SystemResource Readiness Check",
"status":"UP"
},
{
"data":{},
"name":"SystemResource Liveness Check",
"status":"UP"
}
],
"status":"UP"
}
You can also access the /health/ready
endpoint by going to the http://localhost:9080/health/ready URL to view the data from the readiness health check. Similarly, access the /health/live
endpoint by going to the http://localhost:9080/health/live URL to view the data from the liveness health check.
Making code changes and recompiling is fast and straightforward. Open Liberty dev mode automatically picks up changes in the .class
files and artifacts, without needing to be restarted. Alternatively, you can run the run
goal and manually repackage or recompile the application by using the mvn package
command or the mvn compile
command while Liberty is running. Dev mode was added to further improve the developer experience by minimizing turnaround times.
Checking the Open Liberty logs
While Liberty is running in the foreground, it displays various console messages in the command-line session. These messages are also logged to the target/liberty/wlp/usr/servers/defaultServer/logs/console.log
file. You can find the complete Liberty logs in the target/liberty/wlp/usr/servers/defaultServer/logs
directory. The console.log
and messages.log
files are the primary log files that contain console output of the running application and the Liberty instance. More logs are created when runtime errors occur or whenever tracing is enabled. You can find the error logs in the ffdc
directory and the tracing logs in the trace.log
file.
In addition to the log files that are generated automatically, you can enable logging of specific Java packages or classes by using the logging
element:
<logging traceSpecification="<component_1>=<level>:<component_2>=<level>:..."/>
The component
element is a Java package or class, and the level
element is one of the following logging levels: off
, fatal
, severe
, warning
, audit
, info
, config
, detail
, fine
, finer
, finest
, all
.
For more information about logging, see the Trace log detail levels, logging element, and Log and trace configuration documentation.
Try enabling detailed logging of the MicroProfile Health feature by adding the logging
element to your configuration file.
Replace the Libertyserver.xml
configuration file.src/main/liberty/config/server.xml
server.xml
1<server description="Sample Liberty server">
2 <!-- tag::features[] -->
3 <featureManager>
4 <feature>restfulWS-3.1</feature>
5 <feature>jsonp-2.1</feature>
6 <feature>jsonb-3.0</feature>
7 <feature>cdi-4.0</feature>
8 <feature>mpMetrics-5.1</feature>
9 <!-- tag::mpHealth[] -->
10 <feature>mpHealth-4.0</feature>
11 <!-- end::mpHealth[] -->
12 <feature>mpConfig-3.1</feature>
13 </featureManager>
14 <!-- end::features[] -->
15
16 <variable name="http.port" defaultValue="9080"/>
17 <variable name="https.port" defaultValue="9443"/>
18
19 <webApplication location="guide-getting-started.war" contextRoot="/" />
20
21 <mpMetrics authentication="false"/>
22
23 <!-- tag::logging[] -->
24 <logging traceSpecification="com.ibm.ws.microprofile.health.*=all" />
25 <!-- end::logging[] -->
26
27 <httpEndpoint host="*" httpPort="${http.port}"
28 httpsPort="${https.port}" id="defaultHttpEndpoint"/>
29
30 <variable name="io_openliberty_guides_system_inMaintenance" value="false"/>
31</server>
After you change the file, Open Liberty automatically reloads its configuration.
Now, when you visit the /health
endpoint, additional traces are logged in the trace.log
file.
When you are done checking out the service, exit dev mode by pressing CTRL+C
in the command-line session where you ran Liberty.
Running the application in a Docker container
To run the application in a container, Docker needs to be installed. For installation instructions, see the Official Docker Docs.
Make sure to start your Docker daemon before you proceed.
To containerize the application, you need a Dockerfile
. This file contains a collection of instructions that define how a Docker image is built, what files are packaged into it, what commands run when the image runs as a container, and other information. You can find a complete Dockerfile
in the start
directory. This Dockerfile
copies the .war
file into a Docker image that contains the Java runtime and a preconfigured Open Liberty runtime.
Run the mvn package
command from the start
directory so that the .war
file resides in the target
directory.
mvn package
To build and containerize the application, run the following Docker build command in the start
directory:
docker build -t openliberty-getting-started:1.0-SNAPSHOT .
The Docker openliberty-getting-started:1.0-SNAPSHOT
image is also built from the Dockerfile
. To verify that the image is built, run the docker images
command to list all local Docker images:
docker images
Your image should appear in the list of all Docker images:
REPOSITORY TAG IMAGE ID CREATED SIZE
openliberty-getting-started 1.0-SNAPSHOT 88173351adfa 2 minutes ago 780MB
Next, run the image as a container:
docker run -d --name gettingstarted-app -p 9080:9080 openliberty-getting-started:1.0-SNAPSHOT
There is a bit going on here, so here’s a breakdown of the command:
Flag | Description |
---|---|
-d |
Runs the container in the background. |
--name |
Specifies a name for the container. |
-p |
Maps the container ports to the host ports. |
The final argument in the docker run
command is the Docker image name.
Next, run the docker ps
command to verify that your container started:
docker ps
Make sure that your container is running and does not have Exited
as its status:
CONTAINER ID IMAGE CREATED STATUS NAMES
4294a6bdf41b openliberty-getting-started 9 seconds ago Up 11 seconds gettingstarted-app
To access the application, go to the http://localhost:9080/system/properties URL.
To stop and remove the container, run the following commands:
docker stop gettingstarted-app && docker rm gettingstarted-app
To remove the image, run the following command:
docker rmi openliberty-getting-started:1.0-SNAPSHOT
Developing the application in a Docker container
The Open Liberty Maven plug-in includes a devc
goal that simplifies developing your application in a Docker container by starting dev mode with container support. This goal builds a Docker image, mounts the required directories, binds the required ports, and then runs the application inside of a container. Dev mode also listens for any changes in the application source code or configuration and rebuilds the image and restarts the container as necessary.
Build and run the container by running the devc goal from the start
directory:
mvn liberty:devc
When you see the following message, Open Liberty is ready to run in dev mode:
**************************************************************
* Liberty is running in dev mode.
Open another command-line session and run the docker ps
command to verify that your container started:
docker ps
Your container should be running and have Up
as its status:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 17af26af0539 guide-getting-started-dev-mode "/opt/ol/helpers/run…" 3 minutes ago Up 3 minutes 0.0.0.0:7777->7777/tcp, 0.0.0.0:9080->9080/tcp, 0.0.0.0:9443->9443/tcp liberty-dev
To access the application, go to the http://localhost:9080/system/properties URL.
Dev mode automatically picks up changes that you make to your application and allows you to run tests by pressing the enter/return
key in the active command-line session.
Update the server.xml
file to change the context root from /
to /dev
.
Replace the Libertyserver.xml
configuration file.src/main/liberty/config/server.xml
server.xml
1<server description="Sample Liberty server">
2 <!-- tag::features[] -->
3 <featureManager>
4 <feature>restfulWS-3.1</feature>
5 <feature>jsonp-2.1</feature>
6 <feature>jsonb-3.0</feature>
7 <feature>cdi-4.0</feature>
8 <feature>mpMetrics-5.1</feature>
9 <!-- tag::mpHealth[] -->
10 <feature>mpHealth-4.0</feature>
11 <!-- end::mpHealth[] -->
12 <feature>mpConfig-3.1</feature>
13 </featureManager>
14 <!-- end::features[] -->
15
16 <variable name="http.port" defaultValue="9080"/>
17 <variable name="https.port" defaultValue="9443"/>
18
19 <!-- tag::webApplication[] -->
20 <webApplication location="guide-getting-started.war" contextRoot="/dev" />
21 <!-- end::webApplication[] -->
22 <mpMetrics authentication="false"/>
23
24 <!-- tag::logging[] -->
25 <logging traceSpecification="com.ibm.ws.microprofile.health.*=all" />
26 <!-- end::logging[] -->
27
28 <httpEndpoint host="*" httpPort="${http.port}"
29 httpsPort="${https.port}" id="defaultHttpEndpoint"/>
30
31 <variable name="io_openliberty_guides_system_inMaintenance" value="false"/>
32</server>
After you make the file changes, Open Liberty automatically reloads its configuration. When you see the following message in your command-line session, Open Liberty is ready to run again:
The server has been restarted.
************************************************************************
* Liberty is running in dev mode.
Update the mpData.js
file to change the url
in the getSystemPropertiesRequest
method to reflect the new context root.
Replace the mpData.js file.
src/main/webapp/js/mpData.js
mpData.js
Update the pom.xml
file to change the context root from /
to /dev
in the maven-failsafe-plugin
to reflect the new context root when you run functional tests.
Replace the pom.xml file.
pom.xml
pom.xml
You can run the tests by pressing the enter/return
key from the command-line session where you started dev mode to verify your change.
You can access the application at the http://localhost:9080/dev/system/properties URL. Notice that the context root is now /dev
.
When you are finished, exit dev mode by pressing CTRL+C
in the command-line session that the container was started from. Exiting dev mode stops and removes the container. To check that the container was stopped, run the docker ps
command.
Running the application from a minimal runnable JAR
So far, Open Liberty was running out of the target/liberty/wlp
directory, which effectively contains an Open Liberty installation and the deployed application. The final product of the Maven build is a server package for use in a continuous integration pipeline and, ultimately, a production deployment.
Open Liberty supports a number of different server packages. The sample application currently generates a usr
package that contains the Liberty runtime and application to be extracted onto an Open Liberty installation.
Instead of creating a server package, you can generate a runnable JAR file that contains the application along with a Liberty runtime. This JAR file can then be run anywhere and deploy your application and runtime at the same time. To generate a runnable JAR file, override the include
property:
mvn liberty:package -Dinclude=runnable
The packaging type is overridden from the usr
package to the runnable
package. This property then propagates to the liberty-maven-plugin
plug-in, which generates the server package based on the openliberty-kernel
package.
When the build completes, you can find the minimal runnable guide-getting-started.jar
file in the target
directory. This JAR file contains only the features
that you explicitly enabled in your server.xml
file. As a result, the generated JAR file is only about 50 MB.
To run the JAR file, first stop the Liberty instance if it’s running. Then, navigate to the target
directory and run the java -jar
command:
java -jar guide-getting-started.jar
When Liberty starts, go to the http://localhost:9080/dev/system/properties URL to access your application that is now running out of the minimal runnable JAR file.
You can stop the Liberty instance by pressing CTRL+C
in the command-line session that the instance runs in.
pom.xml
1<?xml version='1.0' encoding='utf-8'?>
2<project xmlns="http://maven.apache.org/POM/4.0.0"
3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5 <modelVersion>4.0.0</modelVersion>
6
7 <groupId>io.openliberty.guides</groupId>
8 <artifactId>guide-getting-started</artifactId>
9 <version>1.0-SNAPSHOT</version>
10 <packaging>war</packaging>
11
12 <properties>
13 <maven.compiler.source>11</maven.compiler.source>
14 <maven.compiler.target>11</maven.compiler.target>
15 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
16 <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
17 <!-- Liberty configuration -->
18 <liberty.var.http.port>9080</liberty.var.http.port>
19 <liberty.var.https.port>9443</liberty.var.https.port>
20 </properties>
21
22 <dependencies>
23 <!-- Provided dependencies -->
24 <dependency>
25 <groupId>jakarta.platform</groupId>
26 <artifactId>jakarta.jakartaee-api</artifactId>
27 <version>10.0.0</version>
28 <scope>provided</scope>
29 </dependency>
30 <dependency>
31 <groupId>org.eclipse.microprofile</groupId>
32 <artifactId>microprofile</artifactId>
33 <version>6.1</version>
34 <type>pom</type>
35 <scope>provided</scope>
36 </dependency>
37 <!-- For tests -->
38 <dependency>
39 <groupId>org.junit.jupiter</groupId>
40 <artifactId>junit-jupiter</artifactId>
41 <version>5.11.1</version>
42 <scope>test</scope>
43 </dependency>
44 <dependency>
45 <groupId>org.jboss.resteasy</groupId>
46 <artifactId>resteasy-client</artifactId>
47 <version>6.2.10.Final</version>
48 <scope>test</scope>
49 </dependency>
50 <dependency>
51 <groupId>org.jboss.resteasy</groupId>
52 <artifactId>resteasy-json-binding-provider</artifactId>
53 <version>6.2.10.Final</version>
54 <scope>test</scope>
55 </dependency>
56 <dependency>
57 <groupId>org.glassfish</groupId>
58 <artifactId>jakarta.json</artifactId>
59 <version>2.0.1</version>
60 <scope>test</scope>
61 </dependency>
62 </dependencies>
63
64 <build>
65 <finalName>${project.artifactId}</finalName>
66 <plugins>
67 <!-- Enable liberty-maven plugin -->
68 <!-- tag::libertyMavenPlugin[] -->
69 <plugin>
70 <groupId>io.openliberty.tools</groupId>
71 <artifactId>liberty-maven-plugin</artifactId>
72 <version>3.10.3</version>
73 </plugin>
74 <!-- end::libertyMavenPlugin[] -->
75 <plugin>
76 <groupId>org.apache.maven.plugins</groupId>
77 <artifactId>maven-war-plugin</artifactId>
78 <version>3.4.0</version>
79 </plugin>
80 <plugin>
81 <groupId>org.apache.maven.plugins</groupId>
82 <artifactId>maven-surefire-plugin</artifactId>
83 <version>3.5.0</version>
84 </plugin>
85 <!-- Plugin to run functional tests -->
86 <!-- tag::maven-failsafe-plugin[] -->
87 <plugin>
88 <groupId>org.apache.maven.plugins</groupId>
89 <artifactId>maven-failsafe-plugin</artifactId>
90 <version>3.5.0</version>
91 <configuration>
92 <systemPropertyVariables>
93 <http.port>${liberty.var.http.port}</http.port>
94 <!-- tag::contextRoot[] -->
95 <context.root>/dev</context.root>
96 <!-- end::contextRoot[] -->
97 </systemPropertyVariables>
98 </configuration>
99 </plugin>
100 <!-- end::maven-failsafe-plugin[] -->
101 </plugins>
102 </build>
103</project>
server.xml
1<server description="Sample Liberty server">
2 <!-- tag::features[] -->
3 <featureManager>
4 <feature>restfulWS-3.1</feature>
5 <feature>jsonp-2.1</feature>
6 <feature>jsonb-3.0</feature>
7 <feature>cdi-4.0</feature>
8 <feature>mpMetrics-5.1</feature>
9 <!-- tag::mpHealth[] -->
10 <feature>mpHealth-4.0</feature>
11 <!-- end::mpHealth[] -->
12 <feature>mpConfig-3.1</feature>
13 </featureManager>
14 <!-- end::features[] -->
15
16 <variable name="http.port" defaultValue="9080"/>
17 <variable name="https.port" defaultValue="9443"/>
18
19 <!-- tag::webApplication[] -->
20 <webApplication location="guide-getting-started.war" contextRoot="/dev" />
21 <!-- end::webApplication[] -->
22 <mpMetrics authentication="false"/>
23
24 <!-- tag::logging[] -->
25 <logging traceSpecification="com.ibm.ws.microprofile.health.*=all" />
26 <!-- end::logging[] -->
27
28 <httpEndpoint host="*" httpPort="${http.port}"
29 httpsPort="${https.port}" id="defaultHttpEndpoint"/>
30
31 <variable name="io_openliberty_guides_system_inMaintenance" value="false"/>
32</server>
Great work! You’re done!
You’ve learned the basics of deploying and updating an application on Open Liberty.
Guide Attribution
Getting started with Open Liberty by Open Liberty is licensed under CC BY-ND 4.0
Prerequisites:
Nice work! Where to next?
What did you think of this guide?
Thank you for your feedback!
What could make this guide better?
Raise an issue to share feedback
Create a pull request to contribute to this guide
Need help?
Ask a question on Stack Overflow