Essencium Backend

To be used together with:

• Essencium Frontend (recommended)
• web-starter/frontend (version >= 1.0.0, not recommended anymore)

Requirements

• JDK 17
• Maven >= 3.x
• PostgreSQL >= 14.x (recommended) or H2 (for development purposes only)

If you are having problems resolving Maven dependencies, check the troubleshooting section.

Project Structure

This repository contains a multi-module Maven project, involving:

• essencium-backend-parent: Parent module, containing common configuration for all submodules
  • essencium-backend: Base functionality, including user management, authentication, security configuration, i18n, etc. This module is used as a Maven dependency in all newly generated essencium projects.
  • essencium-backend-development: Minimalist example project using essencium-backend as base-library. Only used for development purposes, i.e. to quickly review and debug changes to the library module.

Development

Setup

1. Import project in IntelliJ
2. Install IntelliJ plugins (Settings -> Plugins)
   • Lombok
   • google-java-format
3. Optional: Start Postgres database using the docker-compose.yml file

Due to the fact that the 'git-pre-commit-hook' currently ignores the integration tests directory for correct formatting of the code, the following command must be executed manually after changes to the integration tests: mvn org.codehaus.mojo:build-helper-maven-plugin:add-test-source@add-integration-test-sources git-code-format:format-code

Run

1. Run the main class in your IDE or execute mvn spring-boot:run
2. Access the backend at http://localhost:8098

Initial Data

See here for documentation about initial default data.

Custom User models

See here for documentation on how to extend the default user entity.

Security

See here for extensive documentation about security, authentication and authorization.

Method-level access management & advanced permission checks

See here for extensive documentation and examples on how to restrict certain users from accessing specific entities or entity properties on controller method level.

See here for documentation and examples on how to perform fine-grained access control on controller method level.

JPA Specifications

See here for details on how to write custom JPA Specifications for data querying.

Postman Collection

See here for details on how to use our pre-built Postman collection, containing request examples for all backend endpoints.

Deployment

See here for details on how to best deploy essencium projects.

Spring Profiles

Different Spring profiles are available to provide default configuration for certain technical aspects.

• development: A profile to be used during development. Includes debug logging, fake e-mail service, local URLs, etc.
• h2: A profile for using H2 as a database backend (alternative to postgres, recommended for development purposes)
• postgres: A profile for using PostgreSQL as a database backend (alternative to h2, recommended in production)
• ldap: A profile to enable and configure LDAP-based user authentication
• oauth: A profile to enable and configure OAuth 2 / OpenID Connect-based user authentication

Profiles can be activated by setting SPRING_PROFILES_ACTIVE environment variable (comma-separated values) or spring.profiles.active in YAML. By default, h2 and development are active. See the section below on how to configure individual properties, including database credentials, OAuth endpoints, etc.

Configuration Options

The following configuration options are available and can be set either in the corresponding application-*.yml config file or as environment variables. This list is not complete, but rather contains the most important variables. Special attention shall be placed on such marked with "⚠️", as these variables are either security-critical or do not have a meaningful default value.

Usually, Essencium-based applications will be deployed as a Docker stack. In this case, it is a good practice to specify all configuration as environment variables inside docker-compose.yml.

	YAML Key	Environment Variable	Default	Description
⚠️	-	APP_URL	http://localhost:8098 in dev profile, undefined otherwise	Public base URL of the application (without trailing slash!)
	spring.profiles.active	SPRING_PROFILES_ACTIVE	development,h2	Which Spring profiles to use (recommended for production: production,postgres)
⚠️	mail.host	MAIL_HOST	localhost	Mail server hostname
⚠️	mail.port	MAIL_PORT	587	Mail server port
⚠️	mail.username	MAIL_USERNAME	-	Mail server username
⚠️	mail.password	MAIL_PASSWORD	-	Mail server password
	mail.smtp.start-tls	MAIL_SMTP_START_TLS	true	Whether to use STARTTLS for SMTP server connection
	mail.branding.*	MAIL_BRANDING_*	-	Styling / CI for mail templates, see application.yaml for more
	sentry.api_url	SENTRY_API_URL	https://sentry.frachtwerk.de/api/0/	URL of Sentry instance to use
	sentry.organization	SENTRY_ORGANIZATION	frachtwerk	Sentry organization
⚠️	sentry.project	SENTRY_PROJECT	-	Sentry project
⚠️	sentry.token	SENTRY_TOKEN	-	Sentry API token (for forwarding feedback requests) (obtain from at https://sentry.frachtwerk.de/settings/frachtwerk/api-keys/)
⚠️	sentry.dsn	SENTRY_DSN	-	Sentry project DSN for error reporting
	sentry.enable-tracing	SENTRY_ENABLE_TRACING	true	Whether to log request traces to Sentry's performance monitoring
	sentry.traces-sample-rate	SENTRY_TRACES_SAMPLE_RATE	0.1	Percentage of requests to trace
	app.auth.jwt.expiration	APP_AUTH_JWT_EXPIRATION	86400	Validity of issued JWT tokens in seconds
⚠️	app.auth.jwt.secret	APP_AUTH_JWT_SECRET	-	Secret to use for signing JWT tokens
	app.cors.allow	APP_CORS_ALLOW	false	Whether to allow CORS requests (all or nothing)
⚠️	spring.datasource.url	SPRING_DATASOURCE_URL	-	Database connection string (see application-h2.yaml and application-postres.yaml for more)
⚠️	spring.datasource.username	SPRING_DATASOURCE_USERNAME	-	Database user
⚠️	spring.datasource.password	SPRING_DATASOURCE_PASSWORD	-	Database password
	app.security.max-failed-logins	APP_SECURITY_MAX_FAILED_LOGINS	10	Maximum amount of wrong user/password events before the user account is blocked! For LDAP / oAuth Login may a much higher limit than 5 useful.
	spring.security.oauth2.client.*	SPRING_SECURITY_OAUTH2_CLIENT_*	-	OAuth 2 / OpenID Connection configuration, see application-oauth.yaml and oauth2.md
	app.auth.ldap.*	APP_AUTH_LDAP_*	-	LDAP configuration, see application-ldap.yaml
	essencium-backend.jpa.table-prefix	ESSENCIUM_BACKEND_JPA_TABLE_PREFIX	-	Defines a prefix for te names of the database tables. FW_ was hardcoded default in previous Starter-Versions. To support databases build on essencium-backend-versions < v2.0.0 FW_ has to be set here.
	essencium-backend.jpa.camel-case-to-underscore	ESSENCIUM_BACKEND_JPA_CAMEL_CASE_TO_UNDERSCORE	-	Since Hibernate changed it's default column naming strategy this parameter was introduced to restore the old behavior. Setting this parameter to true hibernates current default is overwritten and default behavior is restored. This is necessary on al deployments that initially used essencium-backend < v2.x.x.

Tooling

• When using the default embedded H2 database the H2 console can be accessed at http://localhost:8098/h2-console
• An auto-generated Swagger API documentation can be accessed at http://localhost:8098/swagger-ui/ (trailing slash required)
• A health endpoint is provided at http://localhost:8098/actuator/health

Testing

The backend lib comprises both unit- and integration tests.

• Unit Tests: mvn -f essencium-backend/pom.xml test
• Integration Tests: mvn -f essencium-backend/pom.xml failsafe:integration-test

Mails

Integration Tests are able to send mails through Ethereal. You can log in and see the messages sent using the following credentials:

user: geo.sipes8@ethereal.email
pass: Du5aaBMb7VEZUjCP9M

Translations

Translations can be defined at the time of development using .properties files as seeds as well as during run time via API calls.

Seed Files

This backend lib comes with a set of default translations for German and English, which are defined in essencium-backend/src/main/resources/default_translation/*.properties.

In addition, a user can bring custom, project-specific translations by providing files of the naming scheme *-xx.properties (where xx refers to a certain locale) in the classpath directory src/main/resources/translation of the respective project.

On startup, matching files in this directory are loaded into the database. Project-specific translations take precedence over default translations, i.e. custom translations override default translations with the same key.

Translations, which are present in a seed file, but not in the database are added. However, translations present in the database, which are missing in the seed files, will still not get deleted from the database.

UI

Translations can also be added at runtime via the Admin-UI.

---

Frachtwerk GmbH