Secure Elasticsearch and database credentials

This step is optional but recommended for production environments.

Plaintext credentials for accessing the database and Elasticsearch can be secured using one of the following approaches:

1. Environment variables (recommended) - credentials are separated from the application configuration and managed independently
2. Property encryption - credentials are stored encrypted in application.properties

The following properties are the most common candidates for securing:

• Database username (spring.datasource.username)
• Database password (spring.datasource.password)
• Elasticsearch username (elasticsearch.cluster.username)
• Elasticsearch password (elasticsearch.cluster.password)

Environment variables (recommended)

The Portal is a Spring Boot application and picks up configuration from environment variables automatically. Environment variable values take precedence over values in application.properties, making this approach ideal for keeping secrets out of configuration files.

The following table shows the mapping between application.properties keys and their environment variable equivalents:

Property	Environment Variable
spring.datasource.username	SPRING_DATASOURCE_USERNAME
spring.datasource.password	SPRING_DATASOURCE_PASSWORD
elasticsearch.cluster.username	ELASTICSEARCH_CLUSTER_USERNAME
elasticsearch.cluster.password	ELASTICSEARCH_CLUSTER_PASSWORD

tip

Any application.properties key can be overridden by an environment variable. Spring Boot converts property names to environment variable names by replacing dots (.) with underscores (_) and converting to uppercase. For example, server.port becomes SERVER_PORT.

See the Spring Boot documentation on externalized configuration for details.

Setting environment variables with systemd

For systemd-managed installations, credentials can be provided through an environment file. This keeps secrets in a dedicated, permission-restricted file separate from application.properties.

Create the environment file:

sudo touch /opt/waratek/portal.env
sudo chown portal:portal /opt/waratek/portal.env
sudo chmod 600 /opt/waratek/portal.env

Add the credential values to the file:

SPRING_DATASOURCE_USERNAME=portal_db_user
SPRING_DATASOURCE_PASSWORD=secret_db_password
ELASTICSEARCH_CLUSTER_USERNAME=portal
ELASTICSEARCH_CLUSTER_PASSWORD=secret_es_password

Create a systemd override to load the environment file:

sudo systemctl edit portal

In the editor that opens, add:

[Service]
EnvironmentFile=/opt/waratek/portal.env

Restart the service to apply:

sudo systemctl restart portal

The credentials in application.properties can be left blank or set to placeholder values - the environment variable values will take precedence.

Container deployments

In containerized environments, pass credentials as environment variables using your container runtime or orchestrator's secrets management (e.g. -e flags, Kubernetes Secrets, Docker Secrets).

Property encryption

As an alternative to environment variables, property values can be encrypted in application.properties using the included encryptProperty.sh script.

The script is located in the scripts directory and takes the plaintext value as the first argument. An optional second argument specifies the encryption algorithm (default: PBEWITHHMACSHA256ANDAES_256).

Example:

% ./scripts/encryptProperty.sh "mconsole"
The property was successfully encrypted.
The full output below can be used as a replacement property in application.properties
or as input to the configuration script.

ENC_PBEWITHHMACSHA256ANDAES_256(e3jF8kP2x+...)

The encrypted value can be used directly in application.properties:

spring.datasource.password=ENC_PBEWITHHMACSHA256ANDAES_256(e3jF8kP2x+...)

Legacy encryption format

The previous encryption format ENC(...) using the PBEWithMD5AndDES algorithm is still supported for backward compatibility. To explicitly use the legacy algorithm:

./scripts/encryptProperty.sh "mconsole" PBEWithMD5AndDES

This produces the legacy format:

spring.datasource.password=ENC(tw2x9+FKx9dysXeXEkXXGQ6mSrQI9Dp5)

Existing application.properties files using ENC(...) values will continue to work without changes.

Java version considerations

The default PBEWITHHMACSHA256ANDAES_256 algorithm requires JCE Unlimited Strength, which is available by default in:

• The bundled Java 21 (no action needed)
• Java 9 and later
• Java 8u161 and later

For Java versions older than 8u161, the AES-256 algorithm is not available by default. Use the legacy algorithm instead:

./scripts/encryptProperty.sh "value" PBEWithMD5AndDES

Custom encryption password

By default, the Portal uses a built-in encryption password for decrypting ENC(...) and ENC_<ALGORITHM>(...) values. To use a custom encryption password, set the JASYPT_ENCRYPTOR_PASSWORD environment variable (or the jasypt.encryptor.password system property) before starting the Portal.