BIOM Diversity application

This project is a multi-project Gradle project for the BIOM Diversity application, allowing to provide (and administer) information about ultra-marine territories and indicators.

The application contains two parts:

• the public facing application, accessible by anyone, where HTML pages are generated by the server to be easily indexable by search engines and shared on social media;
• the admin application, under the path /admin, accessible only by administrators (who need to sign in using a login and a password), which is used to administer the content (indicators, eco-gestures, pages, etc.) displayed in the public-facing application.

Sub-projects

The various sub-projects are:

• backend: the Java, Spring Boot application containing the code of the backend HTTP services used by the administration application, as well as the server-generated page templates and logic for the public-facing application;
• frontend: the CSS and JS sources used by the public-facing application, bundled by Webpack;
• admin: the source code of the Angular administration application;
• e2e: the source code of the end-to-end tests written using Cypress;
• platform: a Gradle platform project allowing to configure the Java dependencies and their versions.

Please read all the above READMEs to understand the various parts, and to learn which commands to execute during development.

Development environment

You need

• a Java 11 SDK
• Docker
• NodeJS
• Yarn

Note that, if you only want to build the application, you don't actually need NodeJS and Yarn: the Gradle build downloads them. And if you only want to assemble the application without running the tests, you don't need Docker either.

During development (and during build, if you want it to run the tests and not just assemble the application), run the command

docker-compose up

to start docker containers for

• a PostgreSQL database server with three databases for development, unit tests, and e2e tests
• a fake smtp server which doesn't actually send any email
• a web app (exposed on port 8025) allowing to consult the emails received by the SMTP server

Note that you can always restart from scratch using docker-compose down.

Build

The build is a traditional Gradle multi-project build, using the Gradle wrapper, where all projects respect the standard life-cycle.

Here are the most important commands:

• ./gradlew assemble: assembles the frontend, admin and backend artifacts for production, and bundles everything in an executable jar file located in backend/build/libs/diversity.jar.
• ./gradlew check: runs all the automated tests, including the end-to-end tests of the e2e project, as well as the linting checks.
• ./gradlew build: assembles and runs the checks
• ./gradlew clean: removes all the build-generated files (artefacts, test results, etc.)

Configuring the application for production

The application is developed using Spring Boot, which provides a configuration mechanism based on properties and profiles. The default values of the properties are defined in backend/src/main/resources/application.yml. But of course, in production, some of these properties should be modified:

• diversity.images.directory: the path to the directory where the uploaded images and pdf documents are written to (and read from)
• diversity.contact.email: the email address where all the contact form messages are sent to
• diversity.contact.subject: a prefix prepended to the subject of the contact form messages before sending them to the contact email
• diversity.security.secret-key: a base-64 encoded secret key used to cryptographically sign the JWT tokens used to identify an administrator user. You can generate a random one using ./gradlew generateSecretKey.
• diversity.indicators.base-url: the base URL of the BIOM indicators server. Set by default to https://odata-indicateurs.mnhn.fr.
• diversity.matomo.host: the Matomo host where page hits are being sent.
• diversity.matomo.site-id: the Matomo Site ID where page hits are being sent. If any of those two matomo properties is left blank, then Matomo will be disabled (the Matomo JavaScript snippet won't even be included in generated pages). This is the case by default: during development and tests, Matomo is not used.
• spring.datasource.url: the JDBC URL to the PostgreSQL database
• spring.datasource.username: the user name used to connect to the database. This user must have the rights to create and update tables and sequences, since that is done by the application at startup.
• spring.datasource.password: the password used to connect to the database
• spring.mail.host: the host of the SMTP server
• spring.mail.xxx: additional mail properties needed to connect to the SMTP server. Also see https://docs.spring.io/spring-boot/docs/2.3.x/reference/htmlsingle/#mail-properties.
• server.port: the port that the web server binds to (8080 by default)
• spring.datasource.hikari.xxx: additional properties to configure the JDBC connection pool, for example in case the application needs more connections than the default (10) in the pool. See https://docs.spring.io/spring-boot/docs/2.3.x/reference/htmlsingle/#data-properties for the list of available properties and https://github.com/brettwooldridge/HikariCP#configuration-knobs-baby for the description of those properties.

Note that the server does not deal with https by default. So it should be exposed via a reverse proxy configured for https, like Apache or Nginx. Configuring such a reverse proxy is out of the scope of this document.

As you can read in the Spring Boot documentation, there are various ways to pass additional properties when running the application (environment variable containing JSON properties, command line arguments, etc.). The simplest is probably to simply have an application.properties file in the current directory when running the jar file, containing the production values for the above properties (and more if needed).

Running the jar file

All you need is a Java 11 runtime environment, and then you can run

java -jar diversity.jar

where diversity.jar is the jar file that has been built as explained above.

Administration users

When the application is started, it creates or migrates the database schema, but doesn't insert any data at all. It's the role of an administrator to create the indicators, eco-gestures, territories, and pages. But the application doesn't create any administrator either, thus making it impossible to sign in and start administering the application.

It's thus necessary to first insert at least one administrator in the table app_user. There is no page or CLI tool to do that, so it must be done by connecting to the database and inserting the user directly, using a query such as

insert into app_user (id, login, hashed_password) values (nextval('app_user_seq'), 'johnny', '<hashed_password>')

The hashed_password string is a base64-encoded salted and hashed password, that you can generate using

./gradlew hashPassword -Ppassword=superSecretPassw0rd

Once this is done, you can go to the https://production-url/admin and sign in using johnny as login, and superSecretPassw0rd as password (where production-url is of course the URL that was chosen for the application).