Add context path to Spring Boot application

Adding a Context Path to Your Spring Boot Application

Learn how to configure a context path for your Spring Boot application, enabling it to run under a specific sub-path (e.g., /myapp) rather than the root (/). This guide covers various methods for different deployment scenarios.

By default, a Spring Boot application deployed as a standalone JAR or WAR (when embedded in a server like Tomcat) runs directly at the root context (/). However, in many enterprise environments, it's common to deploy multiple applications on the same server or behind a reverse proxy, each accessible via a unique context path (e.g., http://localhost:8080/my-app). This article will guide you through the different ways to configure a context path for your Spring Boot application, ensuring it integrates seamlessly into your deployment architecture.

Understanding the Context Path

The context path is a prefix to the URL that identifies a web application on a server. For example, if your application is configured with a context path of /api, then all its endpoints will be accessible under http://yourdomain.com/api/your-endpoint. This is crucial for organizing multiple applications on a single domain or port, and for routing requests correctly through proxies and load balancers.

flowchart TD
    A[User Request] --> B{Reverse Proxy / Load Balancer}
    B --> |"/api/*"| C[Spring Boot App (Context: /api)]
    B --> |"/admin/*"| D[Admin App (Context: /admin)]
    C --> E[Application Logic]
    D --> F[Admin Logic]

How a context path helps route requests in a multi-application environment.

Configuring Context Path in application.properties/yml

The most common and recommended way to set the context path for a Spring Boot application is through its configuration files: application.properties or application.yml. This method is straightforward and works for both embedded servers (like Tomcat, Jetty, Undertow) and when deploying as a WAR to an external server.

application.properties

server.servlet.context-path=/my-app

application.yml

server:
  servlet:
    context-path: /my-app

Setting Context Path via Command Line Arguments

For quick testing or dynamic deployments, you can override the context path configured in application.properties or application.yml by passing it as a command-line argument when starting your Spring Boot application. This is particularly useful in containerized environments or CI/CD pipelines where configuration might be injected at runtime.

java -jar your-app.jar --server.servlet.context-path=/api-v1

Starting a Spring Boot application with a command-line context path.

Configuring Context Path for WAR Deployments

When deploying a Spring Boot application as a WAR file to an external servlet container (like a standalone Tomcat, JBoss, or WebLogic), the context path is typically determined by the name of the WAR file itself or by the server's deployment configuration. However, you can still influence it from within your Spring Boot application.

If you deploy my-app.war to Tomcat's webapps directory, it will usually be accessible at /my-app. If you want to explicitly define it, you can still use the server.servlet.context-path property. The external server's configuration might override this, so it's essential to check your specific server's deployment settings.

Programmatic Configuration (Advanced)

While less common for setting the primary context path, you can also programmatically configure the embedded servlet container. This method offers fine-grained control but is generally not needed for simple context path adjustments.

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

@Configuration
public class ServletContainerConfig {

    @Bean
    public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> webServerFactoryCustomizer() {
        return factory -> factory.setContextPath("/programmatic-app");
    }
}

Programmatic configuration of the context path using WebServerFactoryCustomizer.

This programmatic approach is more suitable for complex scenarios, such as conditionally setting the context path based on profiles or external factors, or when you need to configure other servlet container properties.

Verifying the Context Path

After configuring your context path, it's crucial to verify that your application is accessible at the expected URL. Start your application and try accessing one of its endpoints. For example, if your application has a /hello endpoint and a context path of /my-app, you should access it at http://localhost:8080/my-app/hello.

1. Configure Context Path

Add server.servlet.context-path=/your-path to application.properties or application.yml.

2. Build and Run

Build your Spring Boot application (e.g., mvn clean package) and run it (java -jar your-app.jar).

3. Test Endpoint

Open your browser or use a tool like curl to access an endpoint, for example: http://localhost:8080/your-path/your-endpoint.

4. Troubleshoot (if needed)

If you encounter issues, check your application logs for startup messages indicating the context path, and ensure no other server configuration is overriding it.