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.
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.
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
.
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 inbackend/build/libs/diversity.jar
../gradlew check
: runs all the automated tests, including the end-to-end tests of thee2e
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.)
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 todiversity.contact.subject
: a prefix prepended to the subject of the contact form messages before sending them to the contact emaildiversity.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 tohttps://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 databasespring.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 databasespring.mail.host
: the host of the SMTP serverspring.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).
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.
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).