Skip to main content

Development

Running Tests​

The following commands runs both unit and integration tests

info

For JPA through Elide Middleware template, please refer to its dedicated setup section first

mvn clean verify

For IT tests, we use Testcontainers instead of jcabi-mysql because the latter is hard to configure and debug and Testcontainers support more types of db, such as mongo

tip

If tests fail with 404 or endpoint-not-working, make sure the port 8080 is not occupied all integration tests runs against webservice running at that port.

Packaging​

mvn clean package

A WAR file named jersey-webservice-template-1.0-SNAPSHOT.war will be generated under target directory for running in Jetty

Running Webservice in Docker (Local Dev & Testing ONLY)​

This Docker image can be used for

  1. decoupling frontend and backend developments, and
  2. making it easy to run E2E testing of application backed by Jersey Webservice Template in CI/CD
caution

Docker designed here is intended for local development and testing purposes ONLY! It is strongly discouraged to run this Docker container in production!

Getting the Image​

We can obtain the image in one of the 2 approaches below:

Docker Hub​

We can pull the image from my docker hub:

docker pull jack20191124/jersey-webservice-template

GitHub​

We could also build the image from source:

git clone https://github.com/QubitPi/jersey-webservice-template.git
cd jersey-webservice-template
mvn clean package
docker build -t jack20191124/jersey-webservice-template .
info
  • The mvn clean package requires JDK 17 which can be setup with instructions here
  • The jack20191124/jersey-webservice-template in the last command is the image name; we could replace that value with anything preferred

Standing up a Container​

When image is built, we can spin up an instance with

docker run --name=jersey-webservice-template -it -p 8080:8080 jack20191124/jersey-webservice-template
  • name=jersey-webservice-template: the container is named "jersey-webservice-template". We can change it accordingly.
  • -p 8080:8080: 8080 is the port where webservice will listen on. With this port forwarding, we will be able to access webservice from host machine web browser at localhost:8080

If we see the following output, it means the container is running properly and ready to accept request such as http://localhost:8080/v1/data/healthcheck

...

2023-10-24 05:21:46.032:INFO :oejss.DefaultSessionIdManager:main: Session workerName=node0
2023-10-24 05:21:46.977:INFO :oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@2892dae4{ROOT.war,/,file:///tmp/jetty-0_0_0_0-8080-ROOT_war-_-any-13760845903749066689/webapp/,AVAILABLE}{/jetty-base/webapps/ROOT.war}
2023-10-24 05:21:46.994:INFO :oejs.AbstractConnector:main: Started ServerConnector@5c8dfc08{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2023-10-24 05:21:47.009:INFO :oejs.Server:main: Started Server@71d44a3{STARTING}[11.0.15,sto=5000] @2947ms

Running Webservice in Standalone Jetty (Production)​

Download Jetty​

For JDK 17, which is the version JWT runs on, it's been tested that Jetty 11.0.15 worked. Hence, we will use "11.0.15" release as an example:

Error loading download-jetty.png

Put the tar.gz file into a location of your choice as the installation path and extract the Jetty binary using

tar -xzvf jetty-home-11.0.15.tar.gz

The extracted directory jetty-home-11.0.15 is the Jetty distribution. We call this directory $JETTY_HOME, which should not be modified.

Setting Up Standalone Jetty​

Our WAR file will be dropped to a directory where Jetty can pick up and run. We call this directory $JETTY_BASE, which is usually different from the $JETTY_HOME. The $JETTY_BASE also contains container runtime configs. In short, the Standalone Jetty container will be setup with

export JETTY_HOME=/path/to/jetty-home-11.0.15
mkdir -p /path/to/jetty-base
cd /path/to/jetty-base
java -jar $JETTY_HOME/start.jar --add-module=annotations,server,http,deploy,servlet,webapp,resources,jsp

where /path/to/ is the absolute path to the directory containing the jetty-home-11.0.15 directory

The --add-module=annotations,server,http,deploy,servlet,webapp,resources,jsp is how we configure the Jetty container.

Lastly, drop the WAR file into /path/to/jetty-base/webapps directory and rename the WAR file to ROOT.war:

mv /path/to/war-file /path/to/jetty-base/webapps/ROOT.war

Running Webservice​

java -jar $JETTY_HOME/start.jar

The webservice will run on port 8080, and you will see the data you inserted

Deployment​

Jersey Webservice Template supports [automatically deploying to AWS through HashiCorp][hashicorp-aws webservice]