Jumpstart Projects with Essencium Backend

To be used together with:

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


  • 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-sequence-model as library. Only used for development purposes, i.e. to quickly review and debug changes to the library module.
    • essencium-backend-identity-model: Implementation of essencium-backend using a Long as the primary key following Hibernates identity strategy.
    • essencium-backend-sequence-model: Implementation of essencium-backend using a Long as the primary key following Hibernates sequence strategy.
    • essencium-backend-uuid-model: Implementation of essencium-backend using a Long as the primary key.



  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


  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.


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.


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 KeyEnvironment VariableDefaultDescription
⚠️-APP_URLhttp://localhost:8098 in dev profile, undefined otherwisePublic base URL of the application (without trailing slash!)
 spring.profiles.activeSPRING_PROFILES_ACTIVEdevelopment,h2Which Spring profiles to use (recommended for production: production,postgres)
⚠️mail.hostMAIL_HOSTlocalhostMail server hostname
⚠️mail.portMAIL_PORT587Mail server port
⚠️mail.usernameMAIL_USERNAME-Mail server username
⚠️mail.passwordMAIL_PASSWORD-Mail server password
 mail.smtp.start-tlsMAIL_SMTP_START_TLStrueWhether to use STARTTLS for SMTP server connection
 mail.branding.*MAIL_BRANDING_*-Styling / CI for mail templates, see application.yaml for more
 sentry.api_urlSENTRY_API_URLhttps://sentry.frachtwerk.de/api/0/URL of Sentry instance to use
 sentry.organizationSENTRY_ORGANIZATIONfrachtwerkSentry organization
⚠️sentry.projectSENTRY_PROJECT-Sentry project
⚠️sentry.tokenSENTRY_TOKEN-Sentry API token (for forwarding feedback requests) (obtain from at https://sentry.frachtwerk.de/settings/frachtwerk/api-keys/)
⚠️sentry.dsnSENTRY_DSN-Sentry project DSN for error reporting
 sentry.enable-tracingSENTRY_ENABLE_TRACINGtrueWhether to log request traces to Sentry's performance monitoring
 sentry.traces-sample-rateSENTRY_TRACES_SAMPLE_RATE0.1Percentage of requests to trace
 app.auth.jwt.expirationAPP_AUTH_JWT_EXPIRATION86400Validity of issued JWT tokens in seconds
⚠️app.auth.jwt.secretAPP_AUTH_JWT_SECRET-Secret to use for signing JWT tokens
 app.cors.allowAPP_CORS_ALLOWfalseWhether to allow CORS requests (all or nothing)
⚠️spring.datasource.urlSPRING_DATASOURCE_URL-Database connection string (see application-h2.yaml and application-postres.yaml for more)
⚠️spring.datasource.usernameSPRING_DATASOURCE_USERNAME-Database user
⚠️spring.datasource.passwordSPRING_DATASOURCE_PASSWORD-Database password
 app.security.max-failed-loginsAPP_SECURITY_MAX_FAILED_LOGINS10Maximum 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-prefixESSENCIUM_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-underscoreESSENCIUM_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.



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


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 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.


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

Download Details:

Author: Frachtwerk

Official Github: https://github.com/Frachtwerk/essencium-backend 

License: LGPL-3.0 license


Jumpstart Projects with Essencium Backend
1.70 GEEK