Setting configuration via environment variables

When developing bundles and apps with map.apps for Developers, you often need to handle configuration that varies between environments (development, testing, production). This includes sensitive data like API keys, database URLs, or service endpoints that should never be hardcoded in your source code.

Environment variables provide a secure and flexible way to manage these configurations. They allow you to keep sensitive information out of your repository while making your applications easily configurable for different deployment scenarios.

In this how-to…​

In this guide, you’ll learn three different approaches to work with environment variables in map.apps for Developers:

  • Setting variables directly when starting the app

  • Using .env files for local development

  • Configuring both system properties and app placeholders

Checklist

To follow this guide, you need:

  • A project based on map.apps for Developers as released for map.apps version 4.20.0 or higher

Understanding environment variable usage

There are two main ways to use environment variables in map.apps for Developers:

  1. Override configuration properties: Replace values in application.properties, like logging levels or service URLs.

  2. Fill placeholders: Replace @@placeholder@@ tokens in your app configurations and bundle manifests.

Both approaches help you avoid hardcoding environment-specific values in your source code.

Method 1: Setting environment variables directly

The most straightforward approach is to set environment variables directly when starting map.apps for Developers. This is useful for one-off configurations or when you need different values for specific runs.

Setting environment variables directly
API_KEY="your-api-key-here" mvn compile -Denv=dev -Pinclude-mapapps-deps

Method 2: Using .env files for persistent configuration

For local development, .env files provide a more convenient way to manage environment variables. This approach is ideal when you have a consistent set of variables you need for development.

Creating a .env file

Create a file named .env in your map.apps for Developers root directory with key-value pairs:

.env file example
API_KEY=your-api-key-here
SERVICE_URL=https://dev-api.example.com

Using the .env file

Once created, the variables are automatically available when you start map.apps for Developers:

mvn compile -Denv=dev -Pinclude-mapapps-deps

Security note: Never commit .env files to your repository.

The .env file should contain sensitive data like API keys and passwords. map.apps for Developers automatically includes .env in the .gitignore file to prevent accidental commits.

Configuration scenarios

Now that you know how to set environment variables, here are the two main ways to use them in map.apps.

Scenario 1: Overriding configuration properties

Use this approach to modify configuration properties defined in application.properties, such as logging levels or service URLs.

Naming convention: convert the property name to uppercase and replace dots with underscores.

Overriding configuration properties
# Override "client.config.logging" → CLIENT_CONFIG_LOGGING
CLIENT_CONFIG_LOGGING=DEBUG mvn compile -Denv=dev -Pinclude-mapapps-deps

Or in your .env file:

CLIENT_CONFIG_LOGGING=DEBUG

Scenario 2: Filling app configuration placeholders

Use this approach to customize app or bundle-specific settings like titles or API endpoints that vary between environments.

JSON and HTML files of app configurations and bundle manifests can contain placeholders in the format @@property_name@@. These placeholders are replaced with environment variable values at runtime.

Example bundle manifest (manifest.json):

{
  ...
  "properties": {
     "endpoint": "@@api.endpoint@@"
  }
  ...
}

Corresponding environment variables:

Environment variables for placeholders
# Set via command line
API_ENDPOINT="https://dev-api.example.com" mvn compile -Denv=dev -Pinclude-mapapps-deps

Or in a .env file:

API_ENDPOINT=https://dev-api.example.com

Summary

Environment variables in map.apps for Developers provide a clean separation between your code and configuration:

  • Use Method 1 (direct setting) for quick tests or CI/CD pipelines

  • Use Method 2 (.env files) for consistent local development

This approach keeps sensitive data secure and makes your apps easily deployable across different environments.