Skip to content

README.md

Latest commit

 

History

History
339 lines (234 loc) · 11.1 KB

README.md

File metadata and controls

339 lines (234 loc) · 11.1 KB

Travis License

patio

patio is a web application that tries to measure the happiness of a given team periodically by asking for a level of happiness between Very bad and Very Good (being Very bad the saddest scenario and Very good the happiest). This repository hosts the backend of the patio project. Cool!

one two one one one

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:

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 (patio-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: ${PATIO_JDBC_URL}
    username: ${PATIO_JDBC_USER}
    password: ${PATIO_JDBC_PASSWORD}
    driverClassName: ${PATIO_JDBC_DRIVER}

And environment variables

Name Description Default value
PATIO_JDBC_URL JDBC url jdbc:postgresql://localhost:5433/patio
PATIO_JDBC_USER JDBC username patio
PATIO_JDBC_PASSWOR JDBC password patio
PATIO_JDBC_DRIVER JDBC driver org.postgresql.Driver
AWS integration

Configuration file section:

aws:
  credentials:
    accessKey: ${PATIO_AWS_ACCESS_KEY}
    secretKey: ${PATIO_AWS_SECRET_KEY}
  mail:
    sourceemail: ${PATIO_AWS_EMAIL_SOURCE}
    region: ${PATIO_AWS_EMAIL_REGION}
    enabled: ${PATIO_AWS_EMAIL_ENABLED}

And environment variables:

Name Description Default value
PATIO_ACCESS_KEY AWS access key
PATIO_SECRET_KEY AWS secret key
PATIO_AWS_EMAIL_SOURCE AWS source email
PATIO_AWS_EMAIL_REGION AWS region
PATIO_AWS_EMAIL_ENABLED Enable AWS mailing
JWT

Configuration file section:

crypto:
  password: SHA-256
  jwt:
    secret: ${PATIO_JWT_SECRET}
    days: ${PATIO_JWT_DAYS}
    algorithm: ${PATIO_JWT_ALGO}
    issuer: ${PATIO_JWT_ISSUER}

And environment variables:

Name Description Default value
PATIO_JWT_SECRET JWT secret mysupersecret
PATIO_JWT_ALGO JWT signature algorithm HS256
PATIO_JWT_ISSUER JWT issuer claim patio
PATIO_JWT_DAYS JWT days before out of date 7
GOOGLE-OAUTH2

Configuration file section:

oauth2:
  apikey: ${PATIO_OAUTH2_KEY}
  apisecret: ${PATIO_OAUTH2_SECRET}
  callback: ${PATIO_OAUTH2_CALLBACK}

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

Name Description Default value
PATIO_OAUTH2_KEY Oauth2 client id
PATIO_OAUTH2_SECRET Oauth2 client secret
PATIO_OAUTH2_CALLBACK Oauth2 callback URL

PATIO_OAUTH2_CALLBACK must match frontend VUE_APP_REDIRECT_URI variable.

DEFAULT USER

Configuration file section:

duser:
  enabled: ${PATIO_DUSER_ENABLED}
  name: ${PATIO_DUSER_NAME}
  email: ${PATIO_DUSER_EMAIL}
  password: ${PATIO_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
PATIO_DUSER_ENABLED Whether or not to insert default user false
PATIO_DUSER_NAME Default user's name
PATIO_DUSER_EMAIL Default user's email
PATIO_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 '...'
}

Technologies

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

Runtime

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

Testing

Building

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.