Create Your First Spring Boot 3 Project

Introduction

In this chapter, you will create and run your first real Spring Boot 3 application. You will generate a project with Spring Initializr, add a simple HTTP endpoint, run it locally, and package it as an executable JAR. This is the core workflow you will repeat in almost every Boot project.

Prerequisites

  • JDK 17 or 21 installed and verified
  • Maven installed and verified
  • IntelliJ IDEA installed
  • Completed setup from 02_installing_java_maven_and_idea.md

What You Will Build

A minimal REST service with one endpoint:

  • Request: GET /hello
  • Response: Hello, Spring Boot 3!

This tiny app is enough to validate your local environment, project structure, and packaging pipeline.

Create the Project with Spring Initializr

Open start.spring.io and use these options:

  • Project: Maven
  • Language: Java
  • Spring Boot: latest stable 3.x
  • Group: com.hellocode
  • Artifact: demo
  • Name: demo
  • Packaging: Jar
  • Java: 17 or 21
  • Dependencies: Spring Web

Download the zip and extract it.

Tip

Keep Coordinates Stable

groupId + artifactId become part of package naming and artifact identity. Pick names you can keep in later chapters.

Project Structure Overview

After extraction, you should see:

text
demo/
  pom.xml
  src/
    main/
      java/com/hellocode/demo/
        DemoApplication.java
      resources/
        application.properties
    test/
      java/com/hellocode/demo/
        DemoApplicationTests.java

Important files:

  • pom.xml: dependency and build config
  • DemoApplication.java: app entry point
  • application.properties: external config file

Open in IntelliJ IDEA

  1. Open IntelliJ IDEA.
  2. Choose Open and select the project root (demo).
  3. Wait for Maven import and indexing.
  4. Confirm Project SDK is Java 17/21.

If Maven dependencies fail to import, run:

bash
mvn -U clean compile

Understand the Main Class

Generated main class:

java
@SpringBootApplication
public class DemoApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Code explanation:

  • @SpringBootApplication enables component scanning and auto-configuration
  • SpringApplication.run boots the Spring context and starts embedded Tomcat

Add Your First Endpoint

Create HelloController.java in the same package:

Why same package?
By default, Spring Boot scans from the main class package downward. Keeping controllers under that package ensures they are discovered automatically.

Run the Application

You can run in two ways.

Option A: IntelliJ Run Button

  • Run DemoApplication.main()

Option B: Maven Command

bash
mvn spring-boot:run

When startup is successful, you should see logs indicating embedded Tomcat started on port 8080.

Test the Endpoint

Use browser or terminal:

bash
curl http://localhost:8080/hello

Expected output:

text
Hello, Spring Boot 3!

If this works, your first Boot app is alive.

Package as an Executable JAR

Run:

bash
mvn clean package

Then start the packaged app:

bash
java -jar target/demo-0.0.1-SNAPSHOT.jar

This validates your build artifact can run independently, which is exactly how many production deployments start.

Common First-Run Issues

Port already in use

Error like Port 8080 was already in use.

Fix options:

  • Stop the process using 8080
  • Or change port in application.properties:
properties
server.port=8081

JAVA_HOME mismatch

Build uses different Java than IDE.

Fix:

  • Check mvn -version
  • Align terminal Java and IntelliJ Project SDK

Dependency download timeout

Often network/proxy/mirror issue.

Fix:

  • Retry with stable network
  • Configure Maven proxy/mirror in settings.xml

Warning

Do not manually copy random JAR files into your project. Always manage dependencies through pom.xml.

Quick Recap

In this chapter, you:

  1. Generated a Boot 3 project
  2. Added your first REST endpoint
  3. Ran the app locally
  4. Packaged and launched a runnable JAR

You now have a complete local development loop.

FAQ

Do I need spring-boot-starter-web for every project?

No. Only add it when your app serves HTTP endpoints. For batch/CLI jobs, choose other starters.

Why does Boot create tests even in a new project?

Because testing is part of the default engineering workflow. You can keep the generated test class and evolve it later.

Can I rename package com.hellocode.demo?

Yes. Just keep your main class and components in consistent package hierarchy so component scanning still works.

Should I use application.yml or application.properties?

Both are supported. yml is often easier to read for nested config; properties is simple for small projects.

Is java -jar enough for production?

For many services, yes as a runtime form. In modern platforms, teams often wrap this JAR into a Docker image for deployment.