Creating and running a project

You do not assemble a Micronaut project by hand: the official Micronaut Launch generator creates it. It gives you a ready pom.xml with matching versions, a main class, a settings file and a first test. The generator is available as a website and as the mn command-line tool, and both produce the same result.

Using the website

Open launch.micronaut.io and choose:

Do not add any Features yet: we will add them one at a time and see what each one changes. Click Generate Project → Download Zip and unpack the archive into a blog folder.

Using the console

If the Micronaut CLI is installed (for example through SDKMAN: sdk install micronaut), one command creates the same project:

mn create-app com.example.blog --build=maven --lang=java --jdk=25
cd blog

The last part of the name (blog) becomes the project and folder name, the rest (com.example) becomes the package.

What is inside

blog/
├── pom.xml                         Maven build, parent micronaut-parent 5.2.1
├── mvnw, mvnw.bat                  Maven wrapper
├── micronaut-cli.yml               which features were chosen in the generator
└── src/
    ├── main/java/com/example/Application.java
    ├── main/resources/application.properties
    ├── main/resources/logback.xml  logging settings
    └── test/java/com/example/BlogTest.java

The main class starts the application:

// src/main/java/com/example/Application.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 the context holding the application's objects and starts the Netty HTTP server. The settings file has a single line so far: micronaut.application.name=blog.

Running

From the project folder run:

./mvnw mn:run

On Windows (cmd or PowerShell) the command is mvnw.bat mn:run. The first run downloads dependencies and takes a couple of minutes. Then Maven prints Watching for changes in [src\main\java, src\main\resources], a banner and the line:

INFO  io.micronaut.runtime.Micronaut - Startup completed in 575ms. Server Running: http://localhost:8080

The mn:run goal watches your files: after you save a source file, the application is rebuilt and restarted automatically. Stop the server with Ctrl+C.

The first request

There are no controllers yet, but the server already answers:

curl -i http://localhost:8080/

HTTP/1.1 404 Not Found
Content-Type: application/json
 
{"_links":{"self":[{"href":"/","templated":false}]},"_embedded":{"errors":[{"message":"Page Not Found"}]},"message":"Not Found"}

A 404 in JSON means the server is working, there is just nothing at /. This is how Micronaut describes all errors by default.

Common mistake

If port 8080 is already taken by another program (for example, a second copy of the application), startup stops:

ERROR i.m.h.server.netty.NettyHttpServer - Unable to start server. Port *:8080 already in use.
ERROR io.micronaut.runtime.Micronaut - Error starting Micronaut server: Unable to start Micronaut server on *:8080

Stop the old process or choose another port with the line micronaut.server.port=8081 in application.properties.