How to Change Default Port and Context Path in Spring Boot (application.properties & YAML)

Every Spring Boot developer hits this wall on day one: you start your app, it boots on port 8080, and everything is fine — until you try to run a second microservice. Then you get a lovely Port 8080 already in use error, and your day goes downhill. In production, you rarely want to run on port 8080 anyway. Security scanners, reverse proxies, and container orchestrators all expect you to configure ports explicitly. The context path is equally critical: running multiple services behind a single load balancer requires unique paths like /api/v1/users, /api/v1/orders, etc. This article covers every way to change the default port and context path in Spring Boot, from the simple application.properties approach to advanced programmatic configuration using TomcatServletWebServerFactory. We'll also cover the subtle differences between Spring Boot 1.x, 2.x, and 3.x — because the API changed, and the official docs sometimes gloss over that. By the end, you'll know how to set these values in application.properties, application.yml, environment variables, command-line arguments, and even via @Configuration beans. We'll also discuss common pitfalls like port conflicts with embedded containers, context path not being applied to Actuator endpoints, and how to debug when things go sideways.

Setting Port and Context Path via application.properties

The simplest and most common way to change the default port and context path in Spring Boot is through application.properties. This file is automatically loaded by Spring Boot from the classpath (typically src/main/resources/). To change the port, add server.port=8081. To change the context path (the base URL prefix), use server.servlet.context-path=/myapp. In Spring Boot 2.x and 3.x, the property is server.servlet.context-path. In Spring Boot 1.x, it was server.context-path — a common pitfall for developers upgrading legacy apps. If you're using Spring Boot 3.0+, note that the property name remains the same as 2.x, but the behavior is identical. Here's a complete example:

# Change port to 9090
server.port=9090

# Set context path to /api/v1
server.servlet.context-path=/api/v1

# Optional: set a custom server header
server.server-header=MyApp-Server

What the Official Docs Won't Tell You

The official Spring Boot docs show the basic properties, but they don't tell you about the subtle bugs. First, server.servlet.context-path does NOT apply to Actuator endpoints by default — you must set management.server.servlet.context-path separately if you want Actuator under a different path. Second, if you use server.port=0, Spring Boot assigns a random port, but that port changes on every restart — great for testing, terrible for production unless you're behind a service mesh. Third, the context path must start with '/' — if you forget, Spring Boot silently prepends it, but your logs will show a different path than expected. Fourth, when using embedded Tomcat, setting server.port to a privileged port (< 1024) on Linux will fail unless you run as root or use authbind. Fifth, the order of precedence matters: command-line arguments override application.properties, which override YAML files. The official docs list the precedence but don't emphasize how easy it is to accidentally override your port in a Dockerfile with CMD ["java", "-jar", "app.jar", "--server.port=8080"] when your application.properties already sets it. This causes confusion when your local dev environment works but production doesn't.

server:
  port: 9090
  servlet:
    context-path: /api/v1

management:
  server:
    port: 9091
    servlet:
      context-path: /actuator

Using Command-Line Arguments and Environment Variables

Spring Boot allows overriding properties via command-line arguments and environment variables. This is essential for containerized deployments (Docker, Kubernetes) where you don't want to rebuild the JAR just to change the port. Command-line arguments take precedence over application.properties: java -jar myapp.jar --server.port=8081 --server.servlet.context-path=/api. Environment variables use uppercase with underscores: SERVER_PORT=8081 and SERVER_SERVLET_CONTEXT_PATH=/api. Note that environment variables are case-insensitive on Windows but case-sensitive on Linux — use uppercase to be safe. The mapping is: server.port becomes SERVER_PORT, server.servlet.context-path becomes SERVER_SERVLET_CONTEXT_PATH. This is a common source of bugs: developers forget the underscore between 'servlet' and 'context', writing SERVER_SERVLETCONTEXTPATH which is ignored.

FROM openjdk:17-jdk-slim
COPY target/myapp.jar app.jar
ENV SERVER_PORT=9090
ENV SERVER_SERVLET_CONTEXT_PATH=/api/v1
ENTRYPOINT ["java", "-jar", "/app.jar"]

Programmatic Configuration with WebServerFactoryCustomizer

For advanced scenarios, you can programmatically configure the embedded server using WebServerFactoryCustomizer<TomcatServletWebServerFactory>. This is useful when you need dynamic port assignment based on external conditions (e.g., reading from a database or a feature flag). You create a @Configuration class that implements WebServerFactoryCustomizer and override the customize method. Inside, you can set the port and context path programmatically. This approach gives you full access to the Tomcat factory, allowing you to set additional properties like connector, SSL, or compression. Note: this only works for the main web server — for Actuator, you need ManagementServerProperties customizer.

import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.boot.web.servlet.server.ConfigurableServletWebServerFactory;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CustomPortConfig implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {

    @Override
    public void customize(ConfigurableServletWebServerFactory factory) {
        // Read from a custom source (e.g., environment variable, DB)
        String port = System.getenv().getOrDefault("APP_PORT", "8080");
        String contextPath = System.getenv().getOrDefault("APP_CONTEXT_PATH", "/");
        
        factory.setPort(Integer.parseInt(port));
        factory.setContextPath(contextPath);
    }
}

Using @Value and @ConfigurationProperties for Port Configuration

Another approach is to inject port and context path values using @Value or @ConfigurationProperties, then pass them to a customizer bean. This is cleaner than hardcoding env var names in the customizer. First, define properties in application.properties: app.port=9090 and app.context-path=/api. Then create a @ConfigurationProperties class, and inject it into the customizer. This approach keeps your configuration centralized and type-safe. However, note that server.port and server.servlet.context-path are already built-in Spring Boot properties — you don't need custom ones unless you have a specific reason (e.g., mapping from a legacy config source).

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private int port = 8080;
    private String contextPath = "/";

    // getters and setters
    public int getPort() { return port; }
    public void setPort(int port) { this.port = port; }
    public String getContextPath() { return contextPath; }
    public void setContextPath(String contextPath) { this.contextPath = contextPath; }
}

Handling Port Conflicts Gracefully

In production, port conflicts happen when two services try to bind to the same port on the same host. Spring Boot's default behavior is to throw a BindException and fail to start. You can handle this more gracefully by using server.port=0 (random port) and then discovering the port at runtime. To get the actual port, inject ServletWebServerApplicationContext and call getWebServer().getPort(). Alternatively, you can use Spring Boot's PortInUseException and implement a retry mechanism. For containerized environments, random ports are fine because the container orchestrator handles port mapping. For bare-metal deployments, use a port range and scan for available ports programmatically.

import org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext;
import org.springframework.context.ApplicationListener;
import org.springframework.context.event.ContextRefreshedEvent;
import org.springframework.stereotype.Component;

@Component
public class PortConflictHandler implements ApplicationListener<ContextRefreshedEvent> {

    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        ServletWebServerApplicationContext ctx = (ServletWebServerApplicationContext) event.getApplicationContext();
        int port = ctx.getWebServer().getPort();
        System.out.println("Application running on port: " + port);
        // Log to monitoring system
    }
}

Context Path and Reverse Proxy Configuration

When running Spring Boot behind a reverse proxy (Nginx, Apache, AWS ALB), the context path interacts with proxy configuration. If you set server.servlet.context-path=/api, your app expects requests at /api/.... The reverse proxy must strip or forward the path correctly. Common issue: the proxy forwards /api/users but the app sees /users because the proxy already stripped the prefix. To fix, use server.forward-headers-strategy=framework in Spring Boot 2.2+ to let the app know it's behind a proxy. Alternatively, set server.use-forward-headers=true (deprecated in 2.2). The context path should match the proxy's location block. If the proxy uses a different prefix (e.g., /app), you must either change the context path or configure the proxy to rewrite paths.

server {
    listen 80;
    server_name example.com;

    location /api/ {
        proxy_pass http://localhost:9090/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Testing Port and Context Path Configuration

Testing port and context path changes is critical before deploying to production. Use Spring Boot's @SpringBootTest with webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT to test with a random port. You can inject TestRestTemplate or WebTestClient to make requests. To verify the context path, use @LocalServerPort to get the actual port and build the URL manually. Alternatively, use @TestPropertySource to override properties for specific tests. For integration tests that check the context path, use RestTemplate with a base URL that includes the context path. Never hardcode ports in tests — always use random ports to avoid conflicts with other running tests.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.web.server.LocalServerPort;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class PortContextPathTest {

    @LocalServerPort
    private int port;

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void testContextPath() {
        String response = restTemplate.getForObject("http://localhost:" + port + "/api/v1/hello", String.class);
        assertThat(response).contains("Hello");
    }
}