Contribute to help us improve!

Are there edge cases or problems that we didn't consider? Is there a technical pitfall that we should add? Did we miss a comma in a sentence?

If you have any input for us, we would love to hear from you and appreciate every contribution. Our goal is to learn from projects for projects such that nobody has to reinvent the wheel.

Let's collect our experiences together to make room to explore the novel!

To contribute click on Contribute to this page on the toolbar.

Configuration

Set configuration via environment variables

The 12-Factor App recommends to set configurations via environments variables. devonfw follows this recommendation.

In both frameworks (Spring Boot and Quarkus) it’s possible to define configuration properties in a application.properties file and reference them via annotations in code. Both frameworks allow to overwrite those properties using environment variables. For links to related articles see the framework specific tab.

  • Spring

  • Quarkus

A detailed overview of Springs configuration mechanisms is available here:

A list of common properties provided by spring can be found here:

The binding from environment variables is described here: https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#default-configsources

A basic overview of defining and using configuration in Quarkus can be found here: https://quarkus.io/guides/config

The Quarkus config reference guide provides a detailed overview of the configuration options in quarkus. It follows the MicroProfile Config specification. Quarkus can read configs from multiple sources. Environment variables follow a certain conversion rule defined by MicroProfiles ConfigSource.

Define a application.properties file with default values

An application.properties file is a good starting point and should contain default values, that are ready to be used in a productive environment. Do not write values there that are not valid in a production environment, as an overwrite can be easily missed. It’s better to not start an application, because of missing configuration, than starting a missconfigured system. The environment specific configuration is done as mentioned above via environment variables.

Do not add local configurations to the SCM

Any kind of configuration that is not designed for production or contains secret information should not be added to the SCM. It is common practice to use a .env file (mostly Quarkus) or a externalized resources/config/application.properties file (Spring Boot) for the configuration of local services. Those files should be added to the .gitignore file. For new developers an example file should be added to the SCM that does only contain the configuration keys and no values. The developer can create and define a valid configuration starting with this.

Naming conventions for configuration properties

As a best practice the configuration properties should follow these naming conventions:

  • build the property-name as a path of segments separated by the dot character (.)

  • segments should get more specific from left to right

  • a property-name should either be a leaf value or a tree node (prefix of other property-names) but never both! So never have something like foo.bar=value and foo.bar.child=value2.

  • start with a segment namespace unique to the context or application

  • a good example would be «myapp».billing.service.email.sender for the sender address of billing service emails send by «myapp».

Security

Storing credentials as plain text in configuration files is not an option.

Plain text credentials or private keys should never be stored or written down, except in dedicated secret stores.

Never commit any plain text credentials in the source code management systems. Those systems are designed to never forget anything! In case any secrets were stored in scm the history needs to be cleaned to completely remove it from scm.

Encryption

Encryption partly solves this problem. The plain text credentials are encrypted using a strong algorithm and masterpassword. The encrypted password is useless for anybody not knowing the masterpassword.

The masterpassword needs to be provided to the system in a secure way. Providing the password is the challenge in this scenario. How and if the password can be provided securely depends highly on the environment.

For encryption jasypt can be used.

  • Spring

  • Quarkus

Use the Spring Boot Jasypt starter. The github repository delivers a god documentation: https://github.com/ulisesbocchio/jasypt-spring-boot

The default encryption options and the algorithm PBEWITHHMACSHA512ANDAES_256 are considered secure enough.

For Quarkus there’s currently no known ready to use library. https://stackoverflow.com/questions/67159572/how-to-encrypt-and-decrypt-using-jasypt-in-quarkus-for-database-password

Vault

The most secure way of providing secrets to the application is using a dedicate secret store. This could be for example HashiCorp Vault

  • Spring

  • Quarkus

Spring provides an integration with HashiCorp Vault. https://spring.io/projects/spring-vault

See the official Quarkus guide for instruction on using HashiCorp Vault https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html