Build a static native Micronaut image on FROM scratch

Steps#

1. Generate the project from Micronaut Launch, with the management feature for /health.

   $ curl -s -o demo-service.zip 'https://launch.micronaut.io/create/default/com.example.demo-service?lang=JAVA&build=MAVEN&test=JUNIT&javaVersion=JDK_21&features=management' && unzip -q demo-service.zip && ls demo-service
   aot-jar.properties
   micronaut-cli.yml
   mvnw
   mvnw.bat
   pom.xml
   README.md
   src
   

   Expected: a Maven project with mvnw. Then cd demo-service; every later command runs there.

2. Pin the Micronaut platform to 4.10.21. Launch generated 5.2.2 on 2026-10-20; this manual is verified on 4.10.21. The version sits on two lines: the parent and micronaut.version.

   $ grep -n '5\.2\.2' pom.xml
   13:    <version>5.2.2</version>
   20:    <micronaut.version>5.2.2</micronaut.version>
   $ sed -i 's|5\.2\.2|4.10.21|g' pom.xml && grep -n '4\.10\.21' pom.xml
   13:    <version>4.10.21</version>
   20:    <micronaut.version>4.10.21</micronaut.version>
   

   Expected: the same two lines, now 4.10.21. If Launch prints another version, replace that one instead.

3. Add a controller that reports the VM it runs on.

   cat > src/main/java/com/example/HelloController.java <<'EOF'
   package com.example;
   
   import io.micronaut.http.annotation.Controller;
   import io.micronaut.http.annotation.Get;
   
   @Controller("/hello")
   public class HelloController {
       @Get
       public String hello() {
           return "vm=" + System.getProperty("java.vm.name");
       }
   }
   EOF
   

   $ ls src/main/java/com/example
   Application.java
   HelloController.java
   

4. Write the Dockerfile and .dockerignore. The builder is the muslib variant, which ships the musl toolchain. -Dpackaging=native-image makes Maven build the executable, and -DbuildArgs=--static,--libc=musl reaches native-image as two separate options. The runtime stage holds nothing but the binary.

   cat > Dockerfile <<'EOF'
   FROM ghcr.io/graalvm/native-image-community:21-muslib-ol9 AS builder
   WORKDIR /app
   COPY .mvn/ .mvn/
   COPY mvnw pom.xml ./
   RUN ./mvnw -q dependency:resolve
   COPY src/ src/
   RUN ./mvnw package -Dpackaging=native-image -DskipTests \
         -DbuildArgs=--static,--libc=musl
   
   FROM scratch
   COPY --from=builder /app/target/demo-service /demo-service
   EXPOSE 8080
   ENTRYPOINT ["/demo-service"]
   EOF
   printf 'target/\n' > .dockerignore
   

   $ ls -A
   aot-jar.properties
   Dockerfile
   .dockerignore
   .gitignore
   micronaut-cli.yml
   .mvn
   mvnw
   mvnw.bat
   pom.xml
   README.md
   src
   

5. Build the image.

   $ time docker build --progress=plain -t demo-service:static .
   …
   #11 13.39 GraalVM Native Image: Generating 'demo-service' (static executable)...
   #11 14.95  Java version: 21.0.2+13, vendor version: GraalVM CE 21.0.2+13.1
   #11 14.95  C compiler: x86_64-linux-musl-gcc (linux, x86_64, 10.2.1)
   #11 14.95  Garbage collector: Serial GC (max heap size: 80% of RAM)
   …
   #11 54.18 Produced artifacts:
   #11 54.18  /app/target/demo-service (executable)
   #11 54.18 Finished generating 'demo-service' in 41.5s.
   #11 54.80 [INFO] BUILD SUCCESS
   #11 DONE 54.9s
   …
   #13 naming to docker.io/library/demo-service:static done
   …
   real	0m57.948s
   

   Expected: (static executable) and x86_64-linux-musl-gcc in the header. Plain (executable) with gcc (redhat, …) means a dynamic glibc binary that won't start on scratch (Failure modes, row 1). This run reused a cached Maven layer (#9 CACHED); a cold-cache build takes longer, see Field notes.

6. Check the image size.

   $ docker image ls demo-service:static
   IMAGE                 ID             DISK USAGE   CONTENT SIZE   EXTRA
   demo-service:static   54933f63f033       97.3MB         24.4MB        
   

   Expected: roughly these numbers. On Docker 29 DISK USAGE counts the binary plus CONTENT SIZE: docker image inspect --format '{{.Size}}' gave 97,325,596 bytes, the binary is 72,879,936 bytes (Verify), and the difference, 24,445,660 bytes, is the 24.4MB in CONTENT SIZE.

7. Start the container.

   $ docker run -d --name demo-static -p 127.0.0.1:8080:8080 demo-service:static
   891b261e529be8ce923b8df27d55cc5c2599fd7a97edc022a2945c177a8abf3c
   $ sleep 2; docker logs demo-static 2>&1 | grep -o 'Startup completed in .*'
   Startup completed in 24ms. Server Running: http://891b261e529b:8080
   

   Expected: a startup line in tens of milliseconds. An exec /demo-service: no such file or directory instead is row 1 of Failure modes.