Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Project Structure and Configuration

Tour a Micronaut project: the Application class, application.yml, environments, property placeholders and the order in which configuration sources win.

A generated Micronaut project is small, which makes it easy to learn where everything lives. There is one build file, one class with a main method, a handful of resource files and a test. The parts that deserve most of your attention are the Application class, which boots the framework, and application.yml (or .properties), which configures it.

This lesson shows both, then explains environments and the order in which configuration sources override each other. The real Micronaut code is read-only. The two TryIt programs are Java stand-ins that reproduce the placeholder syntax and the precedence rules so you can experiment.

The Application class

The entry point is an ordinary class with a main method:

Java
package com.example;

import io.micronaut.runtime.Micronaut;

public class Application {
    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
    }
}

Micronaut.run creates an ApplicationContext, loads the generated bean definitions, applies configuration, starts the embedded Netty server (if the HTTP server module is present) and keeps the program alive. Passing Application.class tells Micronaut which package to treat as the root for bean discovery: beans in com.example and sub-packages are found, and beans in unrelated packages are not.

You can customize startup with the builder form:

Java
Micronaut.build(args)
         .mainClass(Application.class)
         .eagerInitSingletons(true)
         .environments("dev")
         .start();

Where files go

Path Purpose
src/main/java Your code and the Application class
src/main/resources/application.yml Default configuration
src/main/resources/application-dev.yml Overrides for the dev environment
src/main/resources/logback.xml Logging setup
src/main/resources/META-INF/ Generated and hand-written metadata
src/test/java Tests; they can have their own application-test.yml
build.gradle.kts or pom.xml Dependencies and plugins

The build output also contains generated sources, such as build/generated/sources/annotationProcessor/java/main. You never edit these, but opening one is a good way to see what the processor wrote for your beans.

application.yml

Configuration is a tree of keys. YAML and .properties (and JSON, Groovy) are all supported, with YAML needing the snakeyaml dependency, which the generator adds for you:

YAML
micronaut:
  application:
    name: shop
  server:
    port: 8081

app:
  greeting: "Hello"
  max-items: 25
  admin-email: ${ADMIN_EMAIL:[email protected]}

The same keys in properties form are micronaut.application.name=shop, micronaut.server.port=8081 and so on. Keys in kebab-case (max-items) and camelCase (maxItems) are treated as the same property, which makes it easy to read them from environment variables.

The value ${ADMIN_EMAIL:[email protected]} is a placeholder: use the property or environment variable ADMIN_EMAIL, and fall back to [email protected] if it is missing. A placeholder without a default and without a value fails startup, which is what you want for required settings.

Reading a value

The simplest way to read a property is @Value or @Property:

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

@Singleton
class Mailer {
    private final String greeting;
    private final int maxItems;

    Mailer(@Property(name = "app.greeting") String greeting,
           @Value("${app.max-items:10}") int maxItems) {
        this.greeting = greeting;
        this.maxItems = maxItems;
    }
}

@Property reads one named key. @Value accepts a placeholder expression and can mix text and several keys. For groups of related settings, a typed @ConfigurationProperties class is better; you will meet it in the configuration chapter.

Environments

An environment is a name that selects extra configuration files. Micronaut detects some automatically (test when running under a test framework, cloud names such as k8s or aws) and you can set others:

Terminal
MICRONAUT_ENVIRONMENTS=dev,local ./gradlew run
java -Dmicronaut.environments=prod -jar app.jar

With the environment dev, Micronaut loads application.yml first, then application-dev.yml on top of it. Values in the second file win. Keep the defaults safe and put developer conveniences in application-dev.yml; never the reverse.

Order of precedence

When the same key is defined in several places, the last source in this simplified list wins (the real list is longer, but this is the practical order):

  1. Default values in code or in application.yml
  2. Environment-specific files such as application-dev.yml
  3. Environment variables
  4. Java system properties (-Dapp.greeting=Hi)
  5. Command-line arguments, where supported

The MICRONAUT_ENVIRONMENTS variable uses upper-case names and underscores. An environment variable APP_MAX_ITEMS can provide app.max-items because Micronaut normalizes the names.

flowchart TB
    A["application.yml"] --> B["application-dev.yml"]
    B --> C["Environment variables"]
    C --> D["System properties"]
    D --> E["Final value used by your beans"]

Each source overrides the one above it.

Stand-in 1: placeholders with defaults

This is a tiny resolver that understands ${KEY:default}, the same syntax Micronaut uses in application.yml and @Value. It is not Micronaut's own resolver, which is far more capable, but the rules for defaults and required values are the same.

Java Resolving ${KEY:default}

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.

Stand-in 2: layered property sources

Now the precedence rules. The Layers class holds several named maps in order, and a lookup returns the value from the last layer that defines it. It also reports which layer supplied the value, a trick worth remembering when you debug "why is my port 8080?".

Java Which source wins?

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.

Practical advice

Keep secrets such as passwords and tokens out of application.yml; reference them as placeholders that read from the environment. Keep environment-specific URLs out of the default file. Name your application with micronaut.application.name, since logs, tracing and service discovery all use it. Next you will write the first endpoint in the first controller lesson; the idea that the build generates classes is expanded in Ahead-of-Time Compilation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does ${PORT:8080} mean in application.yml?

    The text after the colon is the default used when the property or environment variable is missing.
  2. 2. With the environment dev active, which file's values win for a key defined in both?

    Environment-specific files load after the default file and override it.
  3. 3. What does Micronaut.run(Application.class, args) also decide?

    The class you pass marks the root package, and beans below it are found.
  4. 4. Which source normally overrides an environment-specific YAML file?

    Environment variables and system properties sit higher in the precedence order than the YAML files.

Summary

  • Application.main calls Micronaut.run, which builds the context and starts the server.
  • Defaults live in application.yml; application-{env}.yml overrides them for an environment.
  • ${KEY:default} placeholders read properties or environment variables with a fallback.
  • Higher sources win: YAML, environment files, environment variables, then system properties.
  • @Property and @Value inject single values; typed configuration classes come later.

Next: Your First Controller