Micronaut – Loading external yaml or configuration file

In this tutorial, we will explore how to load an external YAML file in a Micronaut application.

Table of contents

• 1. Why Load External Configuration Files?
• 2. Defining an External YAML File
• 3. Configuring Micronaut to Load the External YAML File
  • Using Command Line Argument
  • Using Environment Variable
• 4. Accessing Configuration Values in Micronaut
  • Using @ConfigurationProperties
  • Run the Application
  • Loads External Configuration File
• 5. Conclusion
• 6. Download Source Code
• 7. References

Technologies used:

• Java 21
• Micronaut 4.7.6
• Maven 3.x

1. Why Load External Configuration Files?

Loading external configuration files allows us to:

• Separate configuration from the application code.
• Support different environments such as development, testing, and production.
• Dynamically update configurations without redeploying the application.

2. Defining an External YAML File

Micronaut supports configuration files in the application.yml format, typically located in the src/main/resources directory. However, we can also load YAML files from external locations.

Let’s create an external YAML file named external-config.yml:

micronaut:
  application:
    name: configuration

app:
  name: "MicronautApp - External"
  version: 999
  supportedLanguages:
    - "English"
    - "Spanish"
    - "French"
  metadata:
    author: "mkyong - External"
    license: "MIT"

Save this file outside the application’s classpath, for example, in /config/external-config.yml.

3. Configuring Micronaut to Load the External YAML File

We can instruct Micronaut to load an external configuration file by specifying the file path using the micronaut.config.files system property or environment variable.

Using Command Line Argument

We can run the application and specify the external configuration file as follows:

java -Dmicronaut.config.files=/config/external-config.yml -jar myapp.jar

Using Environment Variable

Alternatively, we can set an environment variable:

export MICRONAUT_CONFIG_FILES=/config/external-config.yml
java -jar myapp.jar

Micronaut will automatically merge this external configuration with existing configurations from application.yml.

4. Accessing Configuration Values in Micronaut

To access values from the external YAML file, we can use @ConfigurationProperties in a Micronaut component.

Using `@ConfigurationProperties`

package com.mkyong.config;

import io.micronaut.context.annotation.ConfigurationProperties;

import java.util.List;
import java.util.Map;

@ConfigurationProperties("app")
public class AppConfig {

    private String name;

    private int version;
    private List<String> supportedLanguages;
    private Map<String, String> metadata;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getVersion() {
        return version;
    }

    public void setVersion(int version) {
        this.version = version;
    }

    public List<String> getSupportedLanguages() {
        return supportedLanguages;
    }

    public void setSupportedLanguages(List<String> supportedLanguages) {
        this.supportedLanguages = supportedLanguages;
    }

    public Map<String, String> getMetadata() {
        return metadata;
    }

    public void setMetadata(Map<String, String> metadata) {
        this.metadata = metadata;
    }
}

We can inject this configuration class into our service:

package com.mkyong.config;

import jakarta.inject.Singleton;

@Singleton
public class AppService {

    private final AppConfig appConfig;

    public AppService(AppConfig appConfig) {
        this.appConfig = appConfig;
    }

    public void printConfig() {
        System.out.println("App Name: " + appConfig.getName());
        System.out.println("App Version: " + appConfig.getVersion());
        System.out.println("Supported Languages: " + String.join(", ", appConfig.getSupportedLanguages()));
        System.out.println("Metadata: " + appConfig.getMetadata());
    }
}

Run the Application

Running the application and print out the configuration files.

package com.mkyong;

import com.mkyong.config.AppService;
import io.micronaut.runtime.Micronaut;
import jakarta.inject.Singleton;

@Singleton
public class Application {

    private final AppService appService;

    public Application(AppService appService) {
        this.appService = appService;
    }

    public static void main(String[] args) {
        Micronaut.run(Application.class, args)      // start app
                .getBean(Application.class).init(); // run startup code
    }

    public void init() {
        appService.printConfig();
    }

}

This is the default configuration files in src/resources.

micronaut:
  application:
    name: configuration

app:
  name: "MicronautApp"
  version: 1
  supportedLanguages:
    - "English"
    - "Spanish"
    - "French"
  metadata:
    author: "mkyong"
    license: "MIT"

Run the application and it prints the default application.yaml.

./mvnw package

$ java -jar target/configuration-0.1.jar

 __  __ _                                  _
|  \/  (_) ___ _ __ ___  _ __   __ _ _   _| |_
| |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
| |  | | | (__| | | (_) | | | | (_| | |_| | |_
|_|  |_|_|\___|_|  \___/|_| |_|\__,_|\__,_|\__|
12:37:17.394 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 424ms. Server Running: http://localhost:8080
App Name: MicronautApp
App Version: 1
Supported Languages: English, Spanish, French
Metadata: {author=mkyong, license=MIT}

Loads External Configuration File

Now, We run the application and specify the external configuration config/external-config.yml file as follows:

java -Dmicronaut.config.files=config/external-config.yml -jar target/configuration-0.1.jar

 __  __ _                                  _
|  \/  (_) ___ _ __ ___  _ __   __ _ _   _| |_
| |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
| |  | | | (__| | | (_) | | | | (_| | |_| | |_
|_|  |_|_|\___|_|  \___/|_| |_|\__,_|\__,_|\__|
12:37:17.394 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 424ms. Server Running: http://localhost:8080
App Name: MicronautApp - External
App Version: 999
Supported Languages: English, Spanish, French
Metadata: {author=mkyong - External, license=MIT}

5. Conclusion

In this tutorial, we learned how to load an external YAML file in a Micronaut application. By leveraging micronaut.config.files, we can manage configurations separately from our application code, making our applications more flexible and scalable.

6. Download Source Code

7. References

• Micronaut Configuration Guide
• Micronaut Environment Configuration
• Micronaut Application Configuration Properties
• Micronaut @ConfigurationProperties Example – Mkyong.com