{"id":19689970,"url":"https://github.com/frachtwerk/essencium-backend","last_synced_at":"2025-04-29T08:35:39.179Z","repository":{"id":189230588,"uuid":"654120472","full_name":"Frachtwerk/essencium-backend","owner":"Frachtwerk","description":"Essencium Backend is a software library built on top of Spring Boot that allows developers to quickly get started on new software projects. Essencium provides, for example, a fully implemented role-rights concept as well as various field-tested solutions for access management and authentication.","archived":false,"fork":false,"pushed_at":"2025-04-25T13:46:18.000Z","size":2609,"stargazers_count":16,"open_issues_count":30,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-25T14:47:27.775Z","etag":null,"topics":["java","spring","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Frachtwerk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-15T12:33:00.000Z","updated_at":"2025-04-25T13:46:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"3bf2ba49-7a30-4be5-a7dc-191c22605eb0","html_url":"https://github.com/Frachtwerk/essencium-backend","commit_stats":null,"previous_names":["frachtwerk/essencium-backend"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frachtwerk%2Fessencium-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frachtwerk%2Fessencium-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frachtwerk%2Fessencium-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frachtwerk%2Fessencium-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Frachtwerk","download_url":"https://codeload.github.com/Frachtwerk/essencium-backend/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251465341,"owners_count":21593864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","spring","spring-boot"],"created_at":"2024-11-11T19:03:55.484Z","updated_at":"2025-04-29T08:35:39.165Z","avatar_url":"https://github.com/Frachtwerk.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Essencium Backend\n\n[![trivy](https://github.com/Frachtwerk/essencium-backend/actions/workflows/trivy.yml/badge.svg)](https://github.com/Frachtwerk/essencium-backend/actions/workflows/trivy.yml)\n[![CodeQL](https://github.com/Frachtwerk/essencium-backend/actions/workflows/codeql.yml/badge.svg)](https://github.com/Frachtwerk/essencium-backend/actions/workflows/codeql.yml)\n[![Essencium CI - Main](https://github.com/Frachtwerk/essencium-backend/actions/workflows/main.yml/badge.svg)](https://github.com/Frachtwerk/essencium-backend/actions/workflows/main.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Frachtwerk_essencium-backend\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Frachtwerk_essencium-backend)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Frachtwerk_essencium-backend\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Frachtwerk_essencium-backend)\n\nTo be used together with:\n\n- Essencium Frontend (recommended)\n- [web-starter/frontend](https://git.frachtwerk.de/fw-dev/web-starter/frontend) (version \u003e= `1.0.0`, not recommended\n  anymore)\n\n## Requirements\n\n- JDK 17\n- Maven \u003e= 3.x\n- PostgreSQL \u003e= 14.x (recommended) or H2 (for development purposes only)\n\nIf you are having problems resolving Maven dependencies, check the [troubleshooting](doc/troubleshooting.md) section.\n\n## Project Structure\n\nThis repository contains a multi-module Maven project, involving:\n\n- [`essencium-backend-parent`](.): Parent module, containing common configuration for all submodules\n  - [`essencium-backend`](essencium-backend): Base functionality, including user management, authentication, security\n    configuration, i18n, etc. This module is used as a Maven dependency in all newly generated essencium projects.\n  - [`essencium-backend-development`](essencium-backend-development): Minimalist example project\n    using `essencium-backend` as base-library. Only used for development purposes, i.e. to quickly review and\n    debug changes to the library module.\n\n## Development\n\n### Setup\n\n1. Import project in IntelliJ\n1. Install IntelliJ plugins (`Settings -\u003e Plugins`)\n    - [Lombok](https://plugins.jetbrains.com/plugin/6317-lombok)\n    - [google-java-format](https://plugins.jetbrains.com/plugin/8527-google-java-format)\n1. Optional: Start Postgres database using\n   the [`docker-compose.yml`](docker/database/docker-compose.yml) file\n\n\u003e Due to the fact that the 'git-pre-commit-hook' currently ignores the integration tests directory for correct\n\u003e formatting of the code, the following command must be executed manually after changes to the integration tests:\n\u003e `mvn org.codehaus.mojo:build-helper-maven-plugin:add-test-source@add-integration-test-sources git-code-format:format-code`\n\n### Run\n\n1. Run the [main class](essencium-backend-development/src/main/java/de/frachtwerk/essencium/backend/SpringBootApp.java)\n   in your IDE **or** execute `mvn spring-boot:run`\n1. Access the backend at http://localhost:8098\n\n## Initial Data\n\n\u003e See [here](doc/initial_data.md) for documentation about initial default data.\n\n## Custom `User` models\n\n\u003e See [here](doc/custom_user.md) for documentation on how to extend the default user entity.\n\n## Security\n\n\u003e See [here](doc/security.md) for extensive documentation about security, authentication and authorization.\n\n## Method-level access management \u0026 advanced permission checks\n\n\u003e See [here](doc/access_management.md) for extensive documentation and examples on how to restrict certain users from\n\u003e accessing specific entities or entity properties on controller method level.\n\n\u003e See [here](doc/advanced_permission_checks.md) for documentation and examples on how to perform fine-grained access\n\u003e control on controller method level.\n\n## JPA Specifications\n\n\u003e See [here](doc/jpa_specifications.md) for details on how to write custom JPA `Specification`s for data querying.\n\n## Postman Collection\n\n\u003e See [here](postman/README.md) for details on how to use our pre-built Postman collection, containing request examples\n\u003e for all backend endpoints.\n\n## Deployment\n\n\u003e See [here](doc/deployment.md) for details on how to best deploy essencium projects.\n\n## Spring Profiles\n\nDifferent Spring profiles are available to provide default configuration for certain technical aspects.\n\n* `development`: A profile to be used during development. Includes debug logging, fake e-mail service, local URLs, etc.\n* `h2`: A profile for using H2 as a database backend (alternative to `postgres`, recommended for development purposes)\n* `postgres`: A profile for using PostgreSQL as a database backend (alternative to `h2`, recommended in production)\n* `ldap`: A profile to enable and configure LDAP-based user authentication\n* `oauth`: A profile to enable and configure OAuth 2 / OpenID Connect-based user authentication\n\nProfiles can be activated by setting `SPRING_PROFILES_ACTIVE` environment variable (comma-separated values)\nor `spring.profiles.active` in YAML. By default, `h2` and `development` are active. See the section below on how to\nconfigure individual properties, including database credentials, OAuth endpoints, etc.\n\n## Configuration Options\n\nThe following configuration options are available and can be set either in the corresponding `application-*.yml` config\nfile or as environment variables. This list is not complete, but rather contains the most important variables. Special\nattention shall be placed on such marked with \"⚠️\", as these variables are either security-critical or do not have a\nmeaningful default value.\n\nUsually, Essencium-based applications will be deployed as a Docker stack. In this case, it is a good practice to specify\nall configuration as environment variables inside `docker-compose.yml`.\n\n|    | YAML Key                                         | Environment Variable                             | Default                                                       | Description                                                                                                                                                                                                                                                                                                   |\n|----|--------------------------------------------------|--------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ⚠️ | -                                                | `APP_URL`                                        | `http://localhost:8098` in `dev` profile, undefined otherwise | Public base URL of the application (without trailing slash!)                                                                                                                                                                                                                                                  |\n|    | `spring.profiles.active`                         | `SPRING_PROFILES_ACTIVE`                         | `development,h2`                                              | Which Spring profiles to use (recommended for production: `production,postgres`)                                                                                                                                                                                                                              | \n| ⚠️ | `mail.host`                                      | `MAIL_HOST`                                      | `localhost`                                                   | Mail server hostname                                                                                                                                                                                                                                                                                          |\n| ⚠️ | `mail.port`                                      | `MAIL_PORT`                                      | `587`                                                         | Mail server port                                                                                                                                                                                                                                                                                              |\n| ⚠️ | `mail.username`                                  | `MAIL_USERNAME`                                  | -                                                             | Mail server username                                                                                                                                                                                                                                                                                          |\n| ⚠️ | `mail.password`                                  | `MAIL_PASSWORD`                                  | -                                                             | Mail server password                                                                                                                                                                                                                                                                                          |\n|    | `mail.smtp.start-tls`                            | `MAIL_SMTP_START_TLS`                            | `true`                                                        | Whether to use STARTTLS for SMTP server connection                                                                                                                                                                                                                                                            |\n|    | `mail.branding.*`                                | `MAIL_BRANDING_*`                                | -                                                             | Styling / CI for mail templates, see [application.yaml](essencium-backend-development/src/main/resources/application.yaml) for more                                                                                                                                                                           |\n|    | `sentry.api_url`                                 | `SENTRY_API_URL`                                 | `https://sentry.frachtwerk.de/api/0/`                         | URL of Sentry instance to use                                                                                                                                                                                                                                                                                 |\n|    | `sentry.organization`                            | `SENTRY_ORGANIZATION`                            | `frachtwerk`                                                  | Sentry organization                                                                                                                                                                                                                                                                                           |\n| ⚠️ | `sentry.project`                                 | `SENTRY_PROJECT`                                 | -                                                             | Sentry project                                                                                                                                                                                                                                                                                                |\n| ⚠️ | `sentry.token`                                   | `SENTRY_TOKEN`                                   | -                                                             | Sentry API token (for forwarding feedback requests) (obtain from at https://sentry.frachtwerk.de/settings/frachtwerk/api-keys/)                                                                                                                                                                               |\n| ⚠️ | `sentry.dsn`                                     | `SENTRY_DSN`                                     | -                                                             | Sentry project DSN for error reporting                                                                                                                                                                                                                                                                        |\n|    | `sentry.traces-sample-rate`                      | `SENTRY_TRACES_SAMPLE_RATE`                      | `0.1`                                                         | Percentage of requests to trace                                                                                                                                                                                                                                                                               |\n|    | `app.auth.jwt.expiration`                        | `APP_AUTH_JWT_EXPIRATION`                        | `86400`                                                       | Validity of issued JWT tokens in seconds                                                                                                                                                                                                                                                                      |\n| ⚠️ | `app.auth.jwt.secret`                            | `APP_AUTH_JWT_SECRET`                            | -                                                             | Secret to use for signing JWT tokens                                                                                                                                                                                                                                                                          |\n|    | `app.cors.allow`                                 | `APP_CORS_ALLOW`                                 | `false`                                                       | Whether to allow CORS requests (all or nothing)                                                                                                                                                                                                                                                               |\n| ⚠️ | `spring.datasource.url`                          | `SPRING_DATASOURCE_URL`                          | -                                                             | Database connection string (see [application-h2.yaml](essencium-backend-development/src/main/resources/application-h2.yaml) and [application-postres.yaml](essencium-backend-development/src/main/resources/application-postgres.yaml) for more)                                                              |\n| ⚠️ | `spring.datasource.username`                     | `SPRING_DATASOURCE_USERNAME`                     | -                                                             | Database user                                                                                                                                                                                                                                                                                                 |\n| ⚠️ | `spring.datasource.password`                     | `SPRING_DATASOURCE_PASSWORD`                     | -                                                             | Database password                                                                                                                                                                                                                                                                                             |\n|    | `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.                                                                                                                                                                |\n|    | `spring.security.oauth2.client.*`                | `SPRING_SECURITY_OAUTH2_CLIENT_*`                | -                                                             | OAuth 2 / OpenID Connection configuration, see [application-oauth.yaml](essencium-backend-development/src/main/resources/application-oauth.yaml) and [oauth2.md](doc/oauth2.md)                                                                                                                                  |\n|    | `app.auth.ldap.*`                                | `APP_AUTH_LDAP_*`                                | -                                                             | LDAP configuration, see [application-ldap.yaml](essencium-backend-development/src/main/resources/application-ldap.yaml)                                                                                                                                                                                          |\n|    | `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 \u003c v2.0.0 `FW_` has to be set here.                                                                                                             |\n|    | `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 \u003c v2.x.x. |\n\n## Tooling\n\n- When using the default embedded H2 database the **H2 console** can be accessed at http://localhost:8098/h2-console\n- An auto-generated **Swagger API documentation** can be accessed at http://localhost:8098/swagger-ui/ (trailing slash\n  required)\n- A **health endpoint** is provided at http://localhost:8098/actuator/health\n\n## Testing\n\nThe backend lib comprises both unit- and integration tests.\n\n- **Unit Tests:** `mvn -f essencium-backend/pom.xml test`\n- **Integration Tests:** `mvn -f essencium-backend/pom.xml failsafe:integration-test`\n\n### Mails\n\nIntegration Tests are able to send mails through [Ethereal](https://ethereal.email/). You\ncan [log in](https://ethereal.email/login) and see the messages sent using the following credentials:\n\u003e user: geo.sipes8@ethereal.email \\\n\u003e pass: Du5aaBMb7VEZUjCP9M\n\n## Translations\n\nTranslations can be defined at the time of development using `.properties` files as seeds as well as during run time via\nAPI calls.\n\n### Seed Files\n\nThis backend lib comes with a set of default translations for German and English, which are defined\nin `essencium-backend/src/main/resources/default_translation/*.properties`.\n\nIn addition, a user can bring custom, project-specific translations by providing files of the naming\nscheme `*-xx.properties` (where `xx` refers to a certain locale) in the classpath\ndirectory `src/main/resources/translation` of the respective project.\n\nOn startup, matching files in this directory are loaded into the database. Project-specific translations take precedence\nover default translations, i.e. custom translations override default translations with the same key.\n\nTranslations, which are present in a seed file, but not in the database are added. However, translations present in the\ndatabase, which are missing in the seed files, will still not get deleted from the database.\n\n### UI\n\nTranslations can also be added at runtime via the Admin-UI.\n\n---\n\nFrachtwerk GmbH\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrachtwerk%2Fessencium-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrachtwerk%2Fessencium-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrachtwerk%2Fessencium-backend/lists"}