Patio is a web application that tries to measure the happiness of a given team periodically by asking for a level of happiness between 1 and 5 (being 1 the saddest scenario and 5 the happiest). This repository hosts the backend of the DWBH project. Cool!

Getting Started

If you'd like to start working on the project. The following sections show you how to do it.

Requirements

What things you need to run the software:

• Docker
• Docker Compose
• JDK 11

To install JDK11 you can also use SDKMAN a great tool to manage JVM related SDKs.

Building

To build the code just execute the task build:

./gradlew build

Building the code implies running:

• static analysis
• code style checking
• test execution
• code coverage generation

If you'd like to enable continuous build execute:

./gradlew build -t

Continuous build means that Gradle does not exit and will re-execute tasks when task file inputs change

Running the tests

To execute only tests do:

./gradlew test

If you'd like to test a specific test or set of tests you can use the --tests option to match the name of the test class/es you want to execute:

./gradlew test --tests *Repository*

There are more ways of executing tests, you can take a look at this blog entry

Running style checking

The project uses Spotless for code style checking. To make sure contributors follow the style rules the project uses :

./gradlew spotlessJavaCheck

If you find any error you can format the conflicted files automatically by executing:

./gradlew spotlessJavaApply

Running missing license headers

To make sure any new file added to src or etc have the license header, run:

./gradlew license --rerun-tasks

If any error arises you can apply the license header just executing:

./gradlew licenseFormat --rerun-tasks

Applying the --rerun-tasks is because sometimes the task result is cached and may lead to unwanted situations.

Running static analysis

The project uses PMD as static analysis checker. To execute PMD for main classes do:

./gradlew pmdMain

And for test classes:

./gradlew pmdTest

Running bug finding

This project uses Spotbugs as tool for spotting possible new bugs. To execute Spotbugs just execute:

./gradlew spotbugsMain

Running dev environment

Running services

When working on development we'll need a PostgreSQL database and sometimes the front end. There's a docker-compose file to bootstrap both systems and make them work with the current back development.

Go to your project's etc/docker (dwbh-api/etc/docker) folder and execute:

docker-compose up -d

Configuration

Before running the API you may want to configure some properties. By default the application looks for the configuration file application.yml. That file doesn't exists by default, but there's the application.yml.template that you can copy to application.yml and change whatever you want there.

When in production environment, there's the application-prod.yml that uses environment variables to complete configuration properties values.

Database

Configuration file:

datasources:
  default:
    url: ${DWBH_JDBC_URL}
    username: ${DWBH_JDBC_USER}
    password: ${DWBH_JDBC_PASSWORD}
    driverClassName: ${DWBH_JDBC_DRIVER}

And environment variables

Name	Description	Default value
DWBH_JDBC_URL	JDBC url	jdbc:postgresql://localhost:5433/dwbh
DWBH_JDBC_USER	JDBC username	dwbh
DWBH_JDBC_PASSWORD	JDBC password	dwbh
DWBH_JDBC_DRIVER	JDBC driver	org.postgresql.Driver

EMAIL

By default, if no other email service has been configured a default dummy service will be used to debug email mailing. You can, for example, configure AWS credentials to enable AWS mailing service.

email:
  source: ${DWBH_EMAIL_SOURCE}
  enabled: ${DWBH_EMAIL_ENABLED}

And environment variables:

Name	Description	Default value
DWBH_EMAIL_SOURCE	Source email
DWBH_EMAIL_ENABLED	Enable mailing

AWS integration

AWS credentials to use AWS services, such as AWS simple mail service.

Configuration file section:

aws:
  credentials:
    accessKey: ${DWBH_AWS_ACCESS_KEY}
    secretKey: ${DWBH_AWS_SECRET_KEY}
    region: ${DWBH_AWS_REGION}

And environment variables:

Name	Description	Default value
DWBH_ACCESS_KEY	AWS access key
DWBH_SECRET_KEY	AWS secret key
DWBH_AWS_REGION	AWS region

JWT

Configuration file section:

crypto:
  password: SHA-256
  jwt:
    secret: ${DWBH_JWT_SECRET}
    days: ${DWBH_JWT_DAYS}
    algorithm: ${DWBH_JWT_ALGO}
    issuer: ${DWBH_JWT_ISSUER}

And environment variables:

Name	Description	Default value
DWBH_JWT_SECRET	JWT secret	mysupersecret
DWBH_JWT_ALGO	JWT signature algorithm	HS256
DWBH_JWT_ISSUER	JWT issuer claim	dwbh
DWBH_JWT_DAYS	JWT days before out of date	7

GOOGLE-OAUTH2

Configuration file section:

oauth2:
  apikey: ${DWBH_OAUTH2_KEY}
  apisecret: ${DWBH_OAUTH2_SECRET}
  callback: ${DWBH_OAUTH2_CALLBACK}

Google Oauth2 settings are required if you want front end to be authenticated using Google authentication.

Name	Description	Default value
DWBH_OAUTH2_KEY	Oauth2 client id
DWBH_OAUTH2_SECRET	Oauth2 client secret
DWBH_OAUTH2_CALLBACK	Oauth2 callback URL

DWBH_OAUTH2_CALLBACK must match frontend VUE_APP_REDIRECT_URI variable.

DEFAULT USER

Configuration file section:

duser:
  enabled: ${DWBH_DUSER_ENABLED}
  name: ${DWBH_DUSER_NAME}
  email: ${DWBH_DUSER_EMAIL}
  password: ${DWBH_DUSER_PASSWORD}

In case you'd like to start the instance with a default user you can use the following environment variables:

Name	Description	Default value
DWBH_DUSER_ENABLED	Whether or not to insert default user	false
DWBH_DUSER_NAME	Default user's name
DWBH_DUSER_EMAIL	Default user's email
DWBH_DUSER_PASSWORD	Default user's plain text password

Running app

Both the database and the front end will be installed and bootstrapped. Now you can execute:

./gradlew run

And the api will use the database register in the docker-compose.yml.

IMPORTANT: Remember that the database is using a docker volume, if you would like to get rid of database data you can do it by executing:

docker volume rm NAME-OF-THE-VOLUME

Loading Fixtures

If it's the first time you are running the application, you may want to load some fixtures to the database first. There're a couple of Gradle tasks to load/clean project's data fixtures:

• fixtures-load
• fixtures-clean

fixtures-load loops over the sql files in 'fixtures/load' and executes them against the database configured in fixtures/fixtures.yaml. The order of execution depends on the file name.

./gradlew fixtures-load

fixtures-clean loops over the sql files in 'fixtures/clean' and executes them against the database configured in fixtures/fixtures.yaml. The order of execution also depends on the file name.

./gradlew fixtures-clean

You can change where the load/clean files are as well as the database configuration file. In your build.gradle you can use the fixtures extension:

fixtures {
  cleanDir '...'
  loadDir '...'
  configFile '...'
}

Logging

All logging configuration can be found in the logback.xml file. By default

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    <logger name="patio" level="DEBUG" />
    <root level="INFO">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

If you'd like to activate SQL queries you can use the following loggers:

<logger name="org.hibernate.SQL" level="ALL" />
<logger name="org.hibernate.type.descriptor.sql" level="TRACE" />

Technologies

The most important technologies you need to be aware of to work on this project are:

Runtime

• Micronaut - A JVM-based micro-framework
• Micronaut Data - Persistence framework
• AWS API - For AWS services (e.g. mailing)

Testing

• JUnit 5 - Java testing library
• Test containers For testing integrations

Building

• Gradle - Building tool

How to contribute

Please see CONTRIBUTING.md for contribution guidelines.

License

https://www.gnu.org/licenses/gpl-3.0.html

Acknowledgments

Thanks to Kaleidos Open Source to make this project possible.