Skip to content

Martini Environmental Variables

Environmental variables are dynamic values that can affect the behavior of processes on a computer. They are often used to configure applications at runtime, providing a flexible way to manage settings without altering the application's source code. In the context of Martini, environmental variables allow for the customization of application behavior based on the specific environment in which the application is running (e.g., development, testing, production).

By leveraging environmental variables, you can create a more flexible and configurable application environment, ensuring that your Martini applications are tailored to their specific operational context.

Setting Environmental Variables

1. Setting Environmental Variables via Docker

When running Martini in a Docker container, you can set environmental variables at the time of container startup. This is done using the -e option in the docker run command. For example:

1
docker run -e VARIABLE_NAME=value martini-image

This command sets the VARIABLE_NAME environmental variable to value for the container running the specified martini-image.

Docker start parameters can also be set with cloud based secrets managers such as AWS Systems Manager Parameter Store

2. Setting Environmental Variables on Windows or Linux

You can set environmental variables in your shell session using the export command. For example, to set an environmental variable using a value retrieved from AWS Systems Manager Parameter Store, you can use the following command:

1
export <variable-name>=$(aws ssm get-parameter --name <parameter-name> --with-decryption --query 'Parameter.Value' --output text)

Note: The --with-decryption option is used to decrypt the parameter value if it's stored as a SecureString, if the parameter is stored as a String you can omit this option.

In this command, <variable-name> is the key name of the variable you want to set. The command retrieves the value from the specified parameter path in AWS and sets it as an environmental variable.

Note: The export command sets the variable for the current shell session only. To set it permanently, add the command to you shell configuration file (e.g., ~/.bashrc or ~/.zshrc for Linux/macOS, or set it in the System Properties for Windows).

3. Fetching Environmental Variables Using Placeholders

See Using Placeholders in Martini for a complete guide to securely injecting environment variables and secrets into your Martini configurations.

Placeholders let you fetch values—such as API keys, database connections, and passwords—without exposing them in your code or configuration files. Use them in your application or package properties to keep your settings flexible and secure.

Overriding Application and Package Properties via Environmental Variables

Environmental variables can be used to override both Martini application properties and package properties at runtime using a special MR_ or mr_ prefix. This mechanism allows you to modify existing configuration without editing the configuration files directly, making it ideal for containerized environments and deployment automation.

Important: The MR_ or mr_ prefix is used exclusively for overriding existing application and package properties. You cannot use this mechanism to add new properties that don't already exist in the respective configurations.

How It Works

  • Property Name: Use MR_ or mr_ prefix for environment variables, followed by the actual property name
  • Detection: Martini automatically detects these prefixed properties at startup
  • Processing: The prefix is removed and the property value is used to override the existing application or package property
  • Priority: These runtime overrides take precedence over properties defined in the files

Naming Convention

When using environmental variables, follow these naming conventions:

  • Use MR_ or mr_ as the prefix
  • Replace dots (.) and hyphens (-) in property names with underscores (_)
  • Use standard environmental variable naming practices

Example

Here are practical examples of overriding properties at runtime:

Overriding Application Properties: Suppose you want to change the REST API base path via the api.rest.base-path property: 

1
export MR_api_rest_base_path=myApi
This changes the REST API base path from the default "api" to "myApi".

Setting HTTP Server Port: 

1
export MR_server_http_port=8080

Overriding Package Properties: 

1
2
3
4
export MR_crm_api_url=https://prod-salesforce.example.com
export MR_crm_api_key=prod_api_key_12345
export MR_notification_email_sender=noreply@company.com
export MR_database_pool_size=20

In all cases, Martini will detect the prefixed property and apply the override to the respective configurations, taking precedence over any existing values from the configuration files.

Tip: To see available properties you can override:

For Application Properties in Martini Designer: Navigate to Martini menu bar → Edit Properties

For Package Properties: Check the package.properties files in your packages under <package-name>/configuration/properties/

Via API: Send a request to the API explorer: 

1
curl -X GET "http://<martini-host-url>/esbapi/properties" -H "accept: application/json"

Note: When using environmental variables, dots (.) in property names should be replaced with underscores (_) as per standard environmental variable naming conventions.

Benefits

This approach provides several advantages:

  • Container-friendly: Perfect for Docker and Kubernetes deployments
  • Security: Keeps sensitive configuration out of files
  • Flexibility: Easy environment-specific configuration
  • Automation: Seamless integration with CI/CD pipelines
  • Cloud-native: Works well with cloud secret management services

Note: Environmental variable overrides take precedence over values defined in configuration files, including both application.properties and package.properties files, allowing for true runtime configuration management.

User Defined External Storage

For external storage not already available in Martini, users can implement the interface Service and then set META-INF/services appropriately with the name of the implementation class. The JAR containing the implementation must be added to the <martini-home>/lib/ext folder, and the Martini Runtime must be restarted so that the library can be detected.