Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Configuration and Validation

Configuration Files and Environments

How Micronaut loads configuration: application.yml, environment variables, system properties, @Value, @Property and environment-specific files, with runnable Java stand-ins.

Almost every Micronaut application needs settings that change between your laptop, the test server and production: a port, a database URL, a feature switch. Micronaut gathers those settings into one flat, ordered set of property sources and lets any bean read them. You never parse a file yourself; you declare what you need and the framework injects it.

The real Micronaut framework is not available on this site, so the real code below is read-only. The two TryIt examples are plain Java stand-ins that imitate the rules (precedence and name normalization) so you can see exactly why a value wins.

Where properties come from

Micronaut reads configuration from several places and merges them. When two places define the same key, the one with higher priority wins. From strongest to weakest, the main sources are:

  1. Command-line arguments passed to main (for example -micronaut.server.port=9000).
  2. Java system properties (-Dmicronaut.server.port=9000).
  3. Operating-system environment variables (MICRONAUT_SERVER_PORT=9000).
  4. Environment-specific files such as application-test.yml.
  5. The default application.yml (or .properties, .json, .toml) on the classpath.

The point of the order is that code and defaults ship inside the jar, while the people who deploy it can override anything from the outside without rebuilding.

Who wins?

Command line Strongest. One-off overrides.
System properties JVM flags such as -Dkey=value.
Environment variables The usual choice in containers.
application.yml Defaults that ship in the jar.

A stronger source replaces the same key from a weaker one.

1 / 2

A typical default file looks like this:

YAML
micronaut:
  application:
    name: notes
  server:
    port: 8080

app:
  greeting: Hello
  page-size: 20

Nested YAML keys become dotted names: micronaut.server.port and app.page-size. The application.yml file lives in src/main/resources.

Relaxed names for environment variables

Environment variable names cannot contain dots or dashes on many systems, so Micronaut matches names loosely. MICRONAUT_SERVER_PORT, micronaut.server.port and micronaut.server-port can all refer to the same setting. A kebab-case key such as page-size is also matched by APP_PAGE_SIZE and by the camel-case spelling pageSize in code.

Reading values in beans

The simplest way is to inject a single value with @Value, which also accepts a default after a colon:

Java
import io.micronaut.context.annotation.Value;
import jakarta.inject.Singleton;

@Singleton
public class GreetingService {

    private final String greeting;
    private final int pageSize;

    public GreetingService(
            @Value("${app.greeting:Hi}") String greeting,
            @Value("${app.page-size:10}") int pageSize) {
        this.greeting = greeting;
        this.pageSize = pageSize;
    }

    public String greet(String name) {
        return greeting + ", " + name + "!";
    }
}

@Property(name = "app.greeting") is the stricter sibling: it injects the value and fails at startup if the key is missing and you gave no default, which is often what you want for required settings. For groups of related settings, prefer a typed class, covered in Typed Configuration.

You can also read values without injection by asking the Environment bean:

Java
import io.micronaut.context.env.Environment;

@Singleton
class Diagnostics {
    Diagnostics(Environment env) {
        int port = env.getProperty("micronaut.server.port", Integer.class).orElse(8080);
        System.out.println("port = " + port);
    }
}

getProperty returns an Optional, so a missing key is an ordinary case you handle, not an exception.

Placeholders

Values can refer to other values and to environment variables with ${...}. The text after the colon is the fallback:

YAML
app:
  database:
    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/notes

On a developer machine nothing is set, so the URL points to localhost:5432. In production the platform sets DB_HOST and the same file works unchanged.

Try it: precedence

This stand-in layers four maps in priority order and prints which source supplied each key. It is an imitation of Micronaut's property sources, not the real loader.

Java Property source precedence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Try it: relaxed names and placeholders

Environment variables use capitals and underscores. This stand-in normalizes both spellings to the same key and expands a ${NAME:default} placeholder.

Java Names and placeholders

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Environments

Micronaut also has named environments. When the application starts it activates a few automatically (test under a test runner, cloud names such as ec2 or k8s when detected) and you can add your own with the MICRONAUT_ENVIRONMENTS variable or -Dmicronaut.environments=dev. For each active environment, Micronaut loads an extra file named application-{env}.yml that overrides the defaults.

YAML
# application-dev.yml
micronaut:
  server:
    port: 8081
logger:
  levels:
    com.example: DEBUG

Keep the base file small and safe, and put only the differences in environment files. Never commit real secrets into any of them; read secrets from environment variables or a secrets store, as explained in Security Fundamentals.

Print the active environments at startup (ApplicationContext.getEnvironment().getActiveNames()) when something behaves oddly. A surprising value is usually an unexpected source or environment, not a bug in your code.

Common mistakes

  • Putting a secret in application.yml and committing it. Use a placeholder: password: ${DB_PASSWORD}.
  • Expecting a weaker source to win. A value in application.yml never beats an environment variable.
  • Typos in keys. @Value with no default fails at startup, which is good; getProperty with orElse hides the typo, so be deliberate about which you want.
  • Using @Value for ten related settings. Switch to a typed configuration class.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which source has the highest priority when the same key is defined in several places?

    Command-line arguments are the strongest source. Environment variables beat the files, and environment-specific files beat the default file.
  2. 2. Which environment variable can set the property micronaut.server.port?

    Micronaut matches names loosely, so upper-case words joined by underscores map to the dotted property.
  3. 3. What does the text after the colon mean in ${app.greeting:Hi}?

    The part after the colon is the fallback value when no source defines the key.
  4. 4. Where should a database password normally come from?

    Secrets stay out of the repository. The file holds a placeholder and the deployment supplies the value.

Summary

  • Micronaut merges several property sources; the command line beats system properties, which beat environment variables, which beat files.
  • Dotted keys, kebab-case and environment-variable spellings all refer to the same property.
  • @Value and @Property inject single values; Environment.getProperty returns an Optional.
  • ${NAME:default} placeholders let one file work everywhere.
  • Environment files (application-dev.yml) override only what differs.

Next: Typed Configuration