Getting a Spring Boot project running for the first time can feel intimidating if you have never used a build tool before, but the whole process takes only a few minutes once you know the steps. This tutorial walks through creating a project with Spring Initializr, understanding what gets generated, and running it successfully, including the small mistakes that trip up most beginners.

Step 1: Open Spring Initializr

Go to start.spring.io in a browser. This is an official tool from the Spring team that generates a ready-to-open project based on a few choices, so there is nothing to install before you even begin.

Step 2: Fill in the basics

  • Project: choose Maven, a build tool that downloads libraries and compiles the project automatically.
  • Language: Java.
  • Spring Boot version: pick the latest stable release shown by default.
  • Group and Artifact: names for the project, for example com.example and demo. These become the base package name.
  • Dependencies: click Add Dependencies and search for Spring Web, then select it.

Step 3: Generate and open

Click Generate. A zip file downloads containing the full project structure. Unzip it and open the folder in an editor built for Java, such as IntelliJ IDEA or VS Code with the Java extensions installed. The editor will usually recognise the pom.xml file and offer to download the required libraries automatically.

Understanding what was generated

A few files matter most at this stage. The pom.xml file lists every dependency the project needs and tells Maven how to build it; this is what changes when a new starter is added later. Inside src/main/java sits a single class ending in Application, marked with @SpringBootApplication, which is the entry point of the whole program. Inside src/main/resources sits application.properties, an initially empty file used for configuration, and a templates folder if a view engine like Thymeleaf was included.

Step 4: Run it

Find the Application class and run its main method, either through the editor's run button or from a terminal:

mvn spring-boot:run

Watch the console output. A successful start ends with a line mentioning Tomcat started on port 8080. Opening http://localhost:8080 in a browser will show a generic error page at this point, which is expected, since no endpoint has been created yet; it confirms the server itself is running correctly.

Common first-run problems

  • Wrong Java version: Spring Boot requires a minimum Java version, usually 17 for recent releases. If the build fails immediately, check the installed Java version with java -version.
  • Port already in use: if something else is already using port 8080, the app will fail to start with a clear error naming the port. Either stop the other program or change server.port in application.properties.
  • No internet on first run: Maven needs to download the dependencies listed in pom.xml the first time, so a working internet connection is required for that initial build.

Where to go next

With a running project in place, the natural next step is understanding the @SpringBootApplication annotation that made the whole thing work, followed by building a first REST endpoint so the app actually responds with something meaningful.