DookuG backend

Table of Contents

• 1. About the project
• 2. Technologies
• 3. Services
• 4. Development Environment
  • 4.1. Running the Full Environment
  • 4.2. Running Components Separately
• 5. Testing
• 6. Release
  • 6.1. Maven release
  • 6.2. Docker Release

1. About the project

Brief overview:

• Document generation module based on templates, which

  • can handle templates in different formats and inject parameter lists into them, then generate the finished document.

  • The module is designed to generate output documents (PDF, XLSX, HTML, TXT, …​) from various template formats with identifiers (TXT, HTML, object, JRXML, …​) by inserting the received parameter(s) into the received template.

  • The solution is based on a microservice architecture.

2. Technologies

Service (jar, war)

• Java 17+

• Java EE 10

• Wildfly 27.0.1.Final

3. Services

• dookug-document-service - contents:

  • Generating document with stored template data

  • Generating document from request data

  • Query content of generated document

  • Generating document from request and stored template data

4. Development Environment

For setting up a development environment, local Docker Compose files are available in the etc/docker-compose directory.

4.1. Running the Full Environment

With a single command, you can launch all the necessary and optional containers, including the database with Liquibase scripts, the application server, Graylog along with its dependencies, and the observability tools.

Start all containers (click to expand)

Currently, Oracle XE and Postgres database profiles are available. Command for running full environment from project root directory:

Start all containers (Oracle)

docker compose -f ./etc/docker-compose/docker-compose.local.all.yml --profile oracle up

Start all containers (PostgreSQL)

docker compose -f ./etc/docker-compose/docker-compose.local.all.yml --profile pg up

Once all containers are up and running, deploy the application as described in the Deploying the Application section.

4.2. Running Components Separately

If needed, you can start individual components separately.

Running the Database (click to expand)

Currently, Oracle XE and PostgreSQL databases are supported. Use one of the following commands to start the database along with Liquibase migrations from the project root directory:

Start Oracle

docker compose -f ./etc/docker-compose/docker-compose.local.oracle.yml up --build --force-recreate

Start PostgreSQL

docker compose -f ./etc/docker-compose/docker-compose.local.postgredb.yml up --build --force-recreate

Running the WildFly Application Server (click to expand)

The application server requires the corresponding database. Use the respective command based on your chosen database:

Start WildFly with Oracle

docker compose -f ./etc/docker-compose/docker-compose.local.dookug-document-service.oracle.yml up --build --force-recreate

Start WildFly with PostgreSQL

docker compose -f ./etc/docker-compose/docker-compose.local.dookug-document-service.postgresql.yml up --build --force-recreate

Deploying the Application (click to expand)

Compile the application:

mvn clean install

Deploy the .war file to the application server

mvn -f dookug-document/dookug-document-service/pom.xml exec:exec -P deploy

Observability (optional, click to expand)

To enable observability tools, run:

Prometheus, Grafana, Jaeger:

docker compose -f ./etc/docker-compose/docker-compose.local.observability.yml up --build --force-recreate

5. Testing

The developer tests are located in the dookug-testsuite Maven module. The tests use the Roaster project and execute fully autonomous REST external calls to the deployed application. They can be run either directly from the developer UI using the JUnit plugin or via Maven by activating the appropriate profile, for example:

mvn verify -Dprofile (1)
mvn verify -Dprofile=sandbox,local (2)

1. default parameters

2. Selected profiles from the etc/config/testsuite/META-INF/roaster-[profile-name].yml configuration files

6. Release

The release process is automated and managed by GitHub Actions. During each release, not only are Maven artifacts built and published, but Docker images are also prepared and released.

6.1. Maven release

The Maven release is generated and uploaded to Sonatype for distribution. You can find the released Maven artifacts at: DookuG Backend - Maven Artifacts

6.2. Docker Release

For Docker releases, both the Dockerfile and the docker-compose file are located in the ./etc/release directory. The released Docker images are pushed to Docker Hub and can be found at the following links:

• DookuG Document Service with PostgreSQL

• DookuG Document Service with Oracle