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:

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:

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

Placeholders enable you to use environmental variables for environment-specific variables and/or secrets. By injecting them as environmental variables these values are not exposed in the code or configuration files. A system administrator can then inject the environmental variables for properties, API keys, database connections, passwords and the like.

You can fetch environmental variables in your application properties or package properties using Placeholders. Placeholder strings follow the format:

1	`${prefix:key:-default value}`

Placeholder Components

Parameter	Required?	Description	Accepted Values	Error Handling
prefix	Yes	Identifies the external storage where the value will be retrieved.	`properties` - retrieve values from the environmental properties. `vaultv1` - retrieve values from HashiCorp Vault KV v1. `vaultv2` - retrieve values from HashiCorp Vault KV v2. `<custom>` - prefix set in user-defined external storage.	If external storage does not exist and default value is not set, an error will be thrown.
key	Yes	The key used to retrieve the value.	Any string	If the key does not exist and the default value is not set, an error will be thrown.
some default value	No	The default value if the key or external storage cannot be found.	Any string	No error handling. If the key is missing, the default value will be used.

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.