Introduction

Migrating an existing Spring application to Spring Boot does not mean throwing away all manual configuration. Spring Boot is opinionated, but it still works well with explicit @Configuration classes, legacy beans you need to preserve, and step-by-step migration from older XML or servlet-container setups. The safest migration is usually incremental: bring in Boot's startup model and dependency management first, then simplify configuration only where it actually helps.

That approach keeps the application running while you move toward Boot conventions. It also makes it easier to spot what should remain manual, such as unusual data-source wiring, multiple contexts, or container-specific deployment behavior.

Start With Build and Entry Point Changes

The first step is usually the build file. In Maven, add Spring Boot's parent or dependency management and replace low-level Spring dependencies with Boot starters where possible.

1<parent>
2  <groupId>org.springframework.boot</groupId>
3  <artifactId>spring-boot-starter-parent</artifactId>
4  <version>3.5.6</version>
5  <relativePath />
6</parent>
7
8<dependencies>
9  <dependency>
10    <groupId>org.springframework.boot</groupId>
11    <artifactId>spring-boot-starter-web</artifactId>
12  </dependency>
13  <dependency>
14    <groupId>org.springframework.boot</groupId>
15    <artifactId>spring-boot-starter-test</artifactId>
16    <scope>test</scope>
17  </dependency>
18</dependencies>

Then add a Boot application class:

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3
4@SpringBootApplication
5public class Application {
6    public static void main(String[] args) {
7        SpringApplication.run(Application.class, args);
8    }
9}

This gives you Boot's startup model without forcing you to delete all existing configuration on day one.

Keep Manual Configuration Where It Still Adds Value

Boot's auto-configuration is helpful, but it is not mandatory everywhere. You can keep manual bean definitions and import them into the Boot application.

1import javax.sql.DataSource;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4import org.springframework.jdbc.datasource.DriverManagerDataSource;
5
6@Configuration
7public class DataSourceConfig {
8    @Bean
9    public DataSource dataSource() {
10        DriverManagerDataSource ds = new DriverManagerDataSource();
11        ds.setDriverClassName("org.postgresql.Driver");
12        ds.setUrl("jdbc:postgresql://localhost:5432/appdb");
13        ds.setUsername("app");
14        ds.setPassword("secret");
15        return ds;
16    }
17}

This is useful when your old app has nonstandard wiring that would be awkward to express through properties alone. Later, if the configuration is ordinary enough, you can move it into application.yml and let Boot configure more of it automatically.

Migrate Web Configuration Carefully

Older Spring apps often use web.xml, XML application contexts, or a traditional WAR deployment to an external servlet container. Boot can support that transition instead of forcing an immediate switch to a fat JAR.

If you still need a WAR, extend SpringBootServletInitializer:

1import org.springframework.boot.builder.SpringApplicationBuilder;
2import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
3
4public class ServletInitializer extends SpringBootServletInitializer {
5    @Override
6    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
7        return application.sources(Application.class);
8    }
9}

That lets the app run inside a servlet container while you modernize the rest of the codebase.

At the same time, move old XML configuration to Java config gradually. There is no prize for converting every file in one risky commit.

Let Boot Help Without Surrendering Control

A practical migration pattern is to adopt Boot's conventions where they reduce noise, then explicitly override where your app is special.

Typical examples include:

• move server port, logging, and simple data-source settings into application.yml
• keep custom @Bean methods for unusual integrations
• exclude auto-configuration only when it actually conflicts with the app

Example property file:

1server:
2  port: 8080
3
4spring:
5  datasource:
6    url: jdbc:postgresql://localhost:5432/appdb
7    username: app
8    password: secret

If Boot starts configuring something you do not want, you can exclude it explicitly rather than abandoning Boot altogether.

Test the Migration in Thin Slices

Migration work fails when too many moving parts change at once. A safer order is:

1. get the application starting under Boot
2. confirm existing endpoints still work
3. move one configuration area at a time
4. add Boot features such as Actuator only after the baseline is stable

Tests are especially important here. If the old app had weak integration coverage, add that before making aggressive configuration changes.

Common Pitfalls

The most common mistake is trying to replace every manual configuration element with Boot properties in a single pass. That creates a migration that is hard to debug.

Another issue is mixing incompatible dependency versions by keeping old Spring artifacts alongside Boot starters. Let Boot manage the Spring version set unless you have a strong reason to override it.

A third problem is assuming Boot requires executable JAR packaging. It does not. WAR deployment is still a valid migration step when the environment requires it.

Summary

• Migrate incrementally: adopt Boot startup and dependency management first.
• Keep manual @Configuration classes where they still express real application-specific behavior.
• Replace legacy XML and servlet setup gradually rather than in one large rewrite.
• Use properties for simple configuration, and explicit beans for unusual wiring.
• Validate the migration in small slices so regressions stay understandable.