Skip to content

Latest commit

 

History

History
248 lines (189 loc) · 10.1 KB

README-source.adoc

File metadata and controls

248 lines (189 loc) · 10.1 KB

todo-backend: quickstart for backend deployment on OpenShift

The todo-backend quickstart demonstrates how to implement a backend that exposes a HTTP API with Jakarta REST to manage a list of ToDo which are persisted in a database with JPA.

This quickstart shows how to setup a local deployment of this backend as well as a deployment on OpenShift to connect to a PostgreSQL database also hosted on OpenShift.

What is it?

The todo-backend quickstart demonstrates how to implement a backend that exposes a HTTP API with Jakarta REST to manage a list of ToDo which are persisted in a database with JPA.

  • The backend exposes a HTTP API to manage a list of todos that complies with the specs defined at todobackend.com.

  • It requires a connection to a PostgreSQL database to persist the todos.

  • It uses the Server Provisioning for local and cloud deployment

  • It can be build with {productName} S2I images for cloud deployment

  • It is deployed on OpenShift using the Helm Chart for {productName}.

Architecture

Architecture with S2I

This backend is built using {productName} S2I Builder and Runtime images.

When the image is built, org.wildfly.plugins:wildfly-maven-plugin plugin provisions the {productName} application server and all the feature packs it needs for its features. The layers are defined in the pom.xml file in the <configuration> section of the org.wildfly.plugins:wildfly-maven-plugin plugin:

<layers>
  <layer>cloud-server</layer>
  <layer>postgresql-datasource</layer>
</layers>

The cloud-server layer provides everything needed to run the backend on OpenShift. This also includes access to Jakarta EE APIs such as CDI, Jakarta REST, JPA, etc. These two layers comes from the {productName} feature pack provided in the {productName} S2I builder image.

The postgresql-datasource layer provides a JDBC driver and DataSource to connect to a PostgreSQL database. It is also provided by org.wildfly:wildfly-datasources-galleon-pack which is included in the WildFly S2I image.

The Git repository for this feature pack is hosted at https://github.com/wildfly-extras/wildfly-datasources-galleon-pack. It provides JDBC drivers and datasources for different databases but for this quickstart, we will only need the postgresql-datasource.

Connection to the PostgreSQL database

As mentioned, the JDBC drivers and datasource configuration that the backend uses to connect to the PostgreSQL database is provided by the org.wildfly:wildfly-datasources-galleon-pack feature pack.

By default, it exposes a single datasource. In the backend, the name of this datasource is ToDos and is specified in the persistence.xml to configure JPA:

<persistence-unit name="primary">
  <jta-data-source>java:jboss/datasources/ToDos</jta-data-source>
</persistence-unit>

At runtime, we only need a few environment variables to establish the connection from {productName} to the external PostgreSQL database:

  • POSTGRESQL_DATABASE - the name of the database (that will be called todos)

  • POSTGRESQL_SERVICE_HOST - the host to connect to the database

  • POSTGRESQL_SERVICE_PORT - The port to connect to the database

  • POSTGRESQL_USER & POSTGRESQL_PASSWORD - the credentials to connect to the database

  • POSTGRESQL_DATASOURCE - The name of the datasources (as mentioned above, it will be ToDos)

Filters for Cross-Origin Resource Sharing (CORS)

The Web frontend for this quickstart uses JavaScript calls to query the backend’s HTTP API. We must enable Cross-Origin Resource Sharing (CORS) filters in the undertow subsystem of {productName} to allow these HTTP requests to succeed.

This script is executed at build time and will provide the following HTTP headers to enabled CORS:

  • Access-Control-Allow-Origin: *

  • Access-Control-Allow-Methods: GET, POST, OPTION, PUT, DELETE, PATCH

  • Access-Control-Allow-Headers: accept, authorization, content-type, x-requested-with

  • Access-Control-Allow-Credentials: true

  • Access-Control-Max-Age: 1

By default, the backend accepts requests from any origin (*). This is only simplicity. It is possible to restrict the allowed origin using the environment variable CORS_ORIGIN at runtime.

Run the Backend Locally

Package the Backend

The backend is packaged and deployed on a provisioned server:

$ mvn clean package -Pprovisioned-server

Run a Local PostgreSQL Database

Before running the backend locally, we need to have a local PostgreSQL database that we can connect to. We use the postgresql docker image to create one:

$ docker run --name todo-backend-db -e POSTGRES_USER=todos -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgres

This will create a database named todos that we can connect to on localhost:5432 with the credentials todos / mysecretpassword.

Run the Application

With the PostgreSQL database running, we can start the backend by passing the required environment variables to connect to the database:

$ ./target/server/bin/standalone.sh -Denv.POSTGRESQL_DATABASE=todos -Denv.POSTGRESQL_DATASOURCE=ToDos -Denv.POSTGRESQL_SERVICE_HOST=localhost -Denv.POSTGRESQL_SERVICE_PORT=5432 -Denv.POSTGRESQL_USER=todos -Denv.POSTGRESQL_PASSWORD=mysecretpassword

The backend is running, and we can use the HTTP API to manage a list of todos:

# get a list of todos
$ curl http://localhost:8080/todo-backend
[]

# create a todo with the title "This is my first todo item!"
$ curl -X POST -H "Content-Type: application/json"  -d '{"title": "This is my first todo item!"}' http://localhost:8080/todo-backend
{"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}%

# get a list of todos with the one that was just created
$ curl http://localhost:8080/todo-backend
[{"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}]

Please note that the quickstart includes integration tests, which may be executed using the following command:

$ mvn verify -Pintegration-testing

Conclusion

This quickstart shows how the datasource feature pack provided by {productName} simplifies the deployment of a {productName} Jakarta EE backend on OpenShift to connect to an external database and exposes an HTTP API.

The use of a Server Provisioned deployment makes it seamless to move from a local deployment for development to a deployment on cloud platforms such as OpenShift and Kubernetes.