MEGA

Make End-of-the-month-process Great Again!

This is the repository holding the sources for our MEGA application, which provides us an aggregated view over our employees ZEP time entries.

MEGA 1.x.x

The first intention was to provide our employees an application where at the beginning of a month the employees can check their time entries of the former month.

MEGA 2.x.x

In this version we implemented features for project managers whereby the project managers can check project related time entries of their project members.

The following image illustrates the service structure of the MEGA services and external services MEGA depends on.

Figure 1. Mega Service Structure

The following services are provided by MEGA:

1. Backend
   The Quarkus microservice representing the REST backend for the frontend application and integrates the external services such as ZEP and GMAIL

2. Frontend
   The Apache service hosting the compiled Angular frontend application which retrieves its data from the backend

3. Database (PostgreSQL)
   The MEGA database which holds transformed and aggregated data retrieved from the ZEP time management system

The following external services are integrated and used by MEGA:

1. OAUTH (Google)
   The OAUTH service provided by Google which is used to authenticate our employees

2. GMAIL (Google)
   The Gmail email service provided by Google which is used by MEGA for communicating with our employees

3. ZEP
   The time management system where all our employees enter their time entries

The following listing shows the technologies used by the project MEGA.

• Quarkus 1.6.1.Final

• OpenJDK 11

• Maven 3.6.3

• node.js 12.x.x+

• npm 6+

• PostgreSQL 10

• Docker (Development)

MEGA depends on an Openshift Infrastructure setup with mega-infrastructure:2.x.

Project setup

The following sections will explain how a developer can setup the local development environment and get MEGA running.

Developer PC Setup

You need the following software suitable for your used platform:

1. OpenJDK 11

2. Maven 3.6.3

3. NodeJS 12.x.x

4. Npm 6+

5. Docker

Backend setup

The backend project is located at ./mega-zep-backend.

• Start local postgres instance
  docker run -p 5432:5432 --env POSTGRES_PASSWORD=mega --env POSTGRES_USER=mega --env POSTGRES_DB=mega --name mega-db postgres:10

• Go to
  cd ./mega-zep-backend

• Build the application
  mvn clean install

• Start quarkus in development mode
  mvn quarkus:dev

The database schema will be created/migrated after the service started with quarkus:dev.

Frontend Setup

The frontend project is located at ./mega-zep-frontend.

1. Install global dependencies
   npm install -g @angular/cli

2. Go to the project
   cd ./mega-zep-frontend/src/main/angular/frontend

3. Install project dependencies
   npm install

4. Start webserver
   npx ng serve

5. Test the frontend
   npx ng test

The frontend will take some time to come up which is due to the compilation process which takes some time.

Secrets

The following file ./mega-zep-backend/.env contains the secret values and has to be added manually by the developers.

/mega-zep-backend/.env

# The auth token provided by ZEP
TOKEN=***
# The gmail password to use
MAILER_PASSWORD=***
## STAGE deployments only, not for local
# The database user
DB_USER=***
# the database users password
DB_PASSWORD=***
# the host:port where to reach the database
DB_HOST=***

Important

Without this file the backend won’t start.

Database

MEGA uses a database to store persistent data whereby the database is managed by liquibase.

Local development with PostgreSQL

For the local development we use Postgres which is automatically setup by liquibase during mvn quarkus:dev startup. We use the liquibase-maven-plugin which provides maven goals to manage the local database. The source definition of our database schema is the JPA datamodel, and we generate the changeset files via the liquibase-maven-plugin.

Important

All liquibase maven goals work on the compiled sources and resources located in ./mega-zep-backend/target/classes/.

How to use Liquibase

The following sections provide information about how to use the liquibase-maven-plugin properly.

How to generate a full changeset?

1. Drop the current database schema
   mvn liquibase:dropAll

2. Generate the changeset
   mvn liquibase:generateChangeLog

Important

Ensure that the generated full changeset is proper and that everything has been defined in the JPA model.

How to generate a diff changeset?

1. Ensure the database is consistent with the current liquibase definitions
   liquibase:update

2. Generate the diff changeset
   mvn liquibase:diff

How to apply a changeset?

1. Apply newly created changeset
   liquibase:update

Important

Liquibase updates only work on consistent database states defined by changeset files, and the state persisted in the liquibase specific tables, so if a changeset has already been applied then it cannot be reapplied again anymore, and the database needs to be dropped and recreated in full.

How to test a new changeset?

1. Try clean install and H2 setup during tests
   mvn clean install

2. Try application in development and Postgres setup
   mvn quarkus:dev

Important

Ensure that the database state is on the current released version.

Test with H2

For the unit tests we use H2 which is automatically setup by liquibase. We always get a new H2 instance for each test execution, therefore there will never be incompatibilities, therefore developers don’t need to anything.