Skip to content

Rework todo-backend README due to Glow, and due to similar content fo… #1163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emmartins wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Rework todo-backend README due to Glow, and due to similar content fo… #1163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 25 additions & 74 deletions todo-backend/README-source.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,14 @@ include::../shared-doc/attributes.adoc[]
:openshift: true
:archiveType: war
:useHelmChartDir: true
:helm-install-prerequisites-openshift: ../todo-backend/helm-install-prerequisites.adoc
:helm-install-prerequisites-kubernetes: ../todo-backend/helm-install-prerequisites.adoc
:helmSetWildFlyArgumentPrefix: wildfly.

[abstract]
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.

ifndef::ProductRelease[]
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.
endif::[]
ifdef::ProductRelease[]
This quickstart shows how to deploy a {productName} application on OpenShift that connects
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.
endif::[]


== What is it?

Expand All @@ -36,16 +27,8 @@ 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 https://todobackend.com/specs/index.html[todobackend.com].
* It requires a connection to a PostgreSQL database to persist the todos.
ifndef::ProductRelease[]
* It uses the Server Provisioning for local and cloud deployment
endif::[]
* It can be build with {productName} S2I images for cloud deployment
ifndef::ProductRelease[]
* It is deployed on OpenShift using the https://docs.wildfly.org/wildfly-charts/[Helm Chart for {productName}].
endif::[]
ifdef::ProductRelease[]
* It is deployed on OpenShift using the https://jbossas.github.io/eap-charts//[Helm Chart for {productName}].
endif::[]
* It is deployed on OpenShift using the https://{helmRepoUrl}/[Helm Chart for {productName}].

// Link to the quickstart source
include::../shared-doc/view-the-source.adoc[leveloffset=+1]
Expand All @@ -59,63 +42,19 @@ include::../shared-doc/system-requirements.adoc[leveloffset=+1]
This backend is built using {productName} S2I Builder and Runtime images.

ifndef::ProductRelease[]
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:

[source,xml]
----
<layers>
<layer>cloud-server</layer>
<layer>postgresql-datasource</layer>
</layers>
----
When the image is built, `org.wildfly.plugins:wildfly-maven-plugin` provisions the {productName} application server and all the feature packs it needs for its features.
endif::[]

ifdef::ProductRelease[]
When the image is built, `org.jboss.eap.plugins:eap-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.jboss.eap.plugins:eap-maven-plugin` plugin:

[source,xml]
----
<layers>
<layer>cloud-server</layer>
<layer>postgresql-datasource</layer>
</layers>
----
When the image is built, `org.jboss.eap.plugins:eap-maven-plugin` provisions the {productName} application server and all the feature packs it needs for its features.
endif::[]

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.

ifndef::ProductRelease[]
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`.
endif::[]

ifdef::ProductRelease[]
The `postgresql-datasource` layer provides a JDBC driver and DataSource to connect to a PostgreSQL database. It is also provided by
the `org.jboss.eap:eap-datasources-galleon-pack` feature pack.

The Git repository for this feature pack is hosted at https://github.com/jbossas/eap-datasources-galleon-pack.
It provides JDBC drivers and datasources for different databases but for this quickstart, we will only need the `postgresql-datasource`.
endif::[]
The plugin discovers most feature packs needed automatically, we just need the `postgresql` add-on, which provides a JDBC driver and Datasource to connect to a PostgreSQL database.

=== Connection to the PostgreSQL database

ifndef::ProductRelease[]
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.
endif::[]
ifdef::ProductRelease[]
As mentioned, the JDBC drivers and datasource configuration that the backend uses to connect to the PostgreSQL database
is provided by the `org.jboss.eap:eap-datasources-galleon-pack` feature pack.
endif::[]
By default the provisioned `postgresql` add-on exposes a single datasource.

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:

[source,xml]
Expand All @@ -139,11 +78,7 @@ The Web frontend for this quickstart uses JavaScript calls to query the backend'
We must enable Cross-Origin Resource Sharing (CORS) filters in the `undertow` subsystem of {productName} to allow
these HTTP requests to succeed.

ifdef::ProductRelease[]
==== Configuration with {productName} S2I

As we use S2I to provision the server and build the application, we provide a CLI script that contains all the commands to create and configure the CORS filters in Undertow. This script is located in the `src/scripts/cors_filters.cli`.
endif::[]

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

Expand Down Expand Up @@ -212,23 +147,39 @@ Please note that the quickstart includes integration tests, which may be execute
$ mvn verify -Pintegration-testing
----

We can also verify that this application is properly working as a ToDo Backend by running its https://todobackend.com/specs/index.html[specs] on it.

Once all tests passed, we can use the https://todobackend.com/client/index.html[todobackend client] to have a Web application connected to the backend.

[NOTE]
====
https://todobackend.com/[todobackend.com] is an external service used to showcase this quickstart.
It might not always be functional but does not impact the availability of this backend.
====

//===========================================================
// Openshift - START
== Run the Backend on OpenShift

// OpenShift
:additional-readme-openshift: true
:helm-install-prerequisites-openshift: ../todo-backend/helm-install-prerequisites.adoc
include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]
include::../todo-backend/additional-readme-openshift.adoc[leveloffset=+1]
:!additional-readme-openshift:
Comment on lines +166 to +168
Copy link
Copy Markdown
Contributor

@kstekovi kstekovi May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:additional-readme-openshift: is correctly unset after the include, but helm-install-prerequisites-openshift (set on the line above) is never unset. This leaks the attribute into subsequent sections. Please add :!helm-install-prerequisites-openshift: here (and similarly :!helm-install-prerequisites-kubernetes: after the Kubernetes section) to mirror the handling of the other attributes.

Copy link
Copy Markdown
Contributor Author

@emmartins emmartins May 18, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

:!helm-install-prerequisites-openshift:

// OpenShift - END
//===========================================================

//===========================================================
== Run the Backend on Kubernetes
:additional-readme-kubernetes: true
:helm-install-prerequisites-kubernetes: ../todo-backend/helm-install-prerequisites.adoc
include::../shared-doc/build-and-run-the-quickstart-with-kubernetes.adoc[leveloffset=+1]
include::../todo-backend/additional-readme-kubernetes.adoc[leveloffset=+1]
:!additional-readme-kubernetes:
:!helm-install-prerequisites-kubernetes:
//===========================================================


== Conclusion

This quickstart shows how the datasource feature pack provided by {productName} simplifies the deployment
Expand Down
70 changes: 0 additions & 70 deletions todo-backend/additional-readme-cloud.adoc
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions todo-backend/additional-readme-kubernetes.adoc
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions todo-backend/additional-readme-openshift.adoc
View file
Open in desktop

This file was deleted.

41 changes: 34 additions & 7 deletions todo-backend/helm-install-prerequisites.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,46 @@
ifndef::ProductRelease[]
ifdef::additional-readme-openshift[]
:additional-readme-cloud-platform: OpenShift
endif::[]
ifdef::additional-readme-kubernetes[]
:additional-readme-cloud-platform: Kubernetes
endif::[]

The Helm Chart for this quickstart contains all the information to build an image from the source code using S2I.
It also deploys the PostGreSQL database to store the data.

[source,options="nowrap"]
[source,options="nowrap",subs="+attributes"]
----
dependencies:
- name: wildfly
repository: http://docs.wildfly.org/wildfly-charts/
- name: {helmRepoName}
repository: {helmRepoUrl}
version: ...
----

So we need to update the dependencies of our Helm Chart.
To update the dependencies of our Helm Chart execute the following command.

[source,options="nowrap",subs="+attributes"]
----
$ helm dependency update charts/
$ helm dependency update charts
----

= Environment variables for PostgreSQL
Copy link
Copy Markdown
Contributor

@kstekovi kstekovi May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section heading uses a level-0 title (= Environment variables for PostgreSQL), but the original in additional-readme-cloud.adoc used === (level 3 subsection). When this file is included inside the cloud deployment sections (with leveloffset applied by the shared docs), this will render at an incorrect level in the output. Please change it to ===.

Copy link
Copy Markdown
Contributor Author

@emmartins emmartins May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should actually be good now, and before was wrong, we should always start adocs with level 1, and use the level-offset, when including the file, as its now done on https://github.com/emmartins/quickstart/blob/fix-eap-todo-os-instructions/shared-doc/build-and-run-the-quickstart-with-openshift.adoc?plain=1#L17


The Helm Chart also contains the environment variables required to connect to the PostgreSQL database.

In local deployment the credentials were passed directly as the values of the environment variables.

For {additional-readme-cloud-platform}, we rely on secrets so that the credentials are never copied outside {additional-readme-cloud-platform}:

[source,options="nowrap"]
----
deploy:
env:
- name: POSTGRESQL_PASSWORD
valueFrom:
configMapKeyRef:
name: postgres-configmap
key: POSTGRES_PASSWORD
----
endif::[]

When the application is deployed, the value for the `POSTGRESQL_PASSWORD` will be taken from the key `POSTGRES_PASSWORD`
in the secret `postgres-configmap`.
Loading