skip to content

How do you change the port and base URL path of a Spring Boot app, and what are the defaults?

level: juniorimportance: must knowfreq 78%

answer

  1. server.* → ServerProperties
  2. port default 8080; 0=random, -1=disabled
  3. context-path default empty, prefixes every URL
  4. @LocalServerPort reads random port
  5. override via CLI / env / yml

basics

~10 s

Set server.port (default 8080) to change the listening port, and server.servlet.context-path (default /) to prefix every URL. Both go in application.properties/application.yml.

solid answer

~40 s

In Spring Boot the embedded server config lives under the `server.*` prefix. `server.port` sets the TCP port the embedded Tomcat listens on; the default is 8080. Special values: `0` binds a random free port (useful for tests to avoid clashes), `-1` disables the HTTP connector. `server.servlet.context-path` sets a base path prefixed to every mapping — default is empty (`/`); setting `/api` makes a `@GetMapping("/users")` reachable at `/api/users`. These come from `ServerProperties`, bound via `@ConfigurationProperties("server")`. You can override per-environment with Spring profiles, env vars (`SERVER_PORT`), or `--server.port=9090` on the command line. For tests, `@SpringBootTest(webEnvironment = RANDOM_PORT)` sets port 0 and injects the real port via `@LocalServerPort`.

code

yaml · 12 lines
yaml
# application.yml
server:
  port: 9090                 # default 8080; 0 = random free port, -1 = disable connector
  servlet:
    context-path: /api       # default empty; a @GetMapping("/users") now serves /api/users

---
# In a test, let the OS pick the port and read it back:
# @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
# class MyIT {
#   @LocalServerPort int port;
# }

go deeper

for a junior

Must know port default 8080 and how to change it plus context-path prefixing.

for a middle

Should know the 0/-1 special values and externalized-config precedence (CLI > env > yml).

for a senior

Explains random-port testing, actuator on management.server.port, and proxy-prefix pitfalls.

for a principal

Frames context-path vs gateway routing decisions and how generated links/redirects honor it across environments.

## What these properties are Spring Boot ships an **embedded servlet container** (Tomcat by default) inside the runnable JAR — there is no external server to configure. Instead you tune it through properties under the `server.*` prefix, which Spring binds to the `org.springframework.boot.autoconfigure.web.ServerProperties` class using `@ConfigurationProperties`. ### `server.port` The TCP port the embedded container listens on. - **Default: `8080`.** - `server.port=0` → Spring asks the OS for any free ephemeral port. Primarily used in integration tests so parallel builds don't collide on a fixed port. - `server.port=-1` → disables the HTTP connector entirely (e.g. a messaging-only or batch app that still boots the web context). ### `server.servlet.context-path` A base path prepended to **every** request mapping in the app. - **Default: empty**, i.e. the app is served from the root `/`. - Example: `server.servlet.context-path=/api` turns a controller method mapped to `/users` into `/api/users`. This is distinct from `spring.mvc.servlet.path` (the DispatcherServlet mapping) and from `spring.webflux.base-path` (the reactive equivalent). - Commonly used behind a reverse proxy / when several apps share a host and are distinguished by path. ## How to set them Any normal Spring externalized-config source works, in precedence order (highest wins): 1. Command line: `java -jar app.jar --server.port=9090` 2. Environment variable: `SERVER_PORT=9090` (relaxed binding uppercases and replaces dots with underscores) 3. `application.properties` / `application.yml`, optionally profile-specific (`application-prod.yml`). ## Gotchas - **Context-path is NOT the same as a proxy prefix.** If a proxy strips `/api` before forwarding, don't also set `context-path=/api` or you'll get double-prefixing / 404s. - Generated links (redirects, Location headers, HATEOAS) respect the context-path, so hardcoding absolute paths that omit it breaks behind a context-path. - `server.port=0` means you cannot know the port from config; read it at runtime via `@LocalServerPort` or a `WebServerInitializedEvent`. - Actuator can be moved to its own port via `management.server.port`, independent of `server.port`. ## When to use Almost every non-trivial deployment sets `server.port` (to fit the platform's expectations) and often `context-path` (to namespace the app behind a shared gateway).

  • What does `server.port=0` do and why use it?
    It binds a random free ephemeral port chosen by the OS. Used mainly in integration tests so concurrent test runs don't collide on a fixed port; you read the actual port back with `@LocalServerPort` or a `WebServerInitializedEvent`.
  • Difference between `server.servlet.context-path` and `spring.mvc.servlet.path`?
    `context-path` is the base path of the whole web app on the container. `spring.mvc.servlet.path` is where the DispatcherServlet is mapped within that app (default `/`). Effective URL = context-path + servlet-path + mapping.

saying these in an interview costs you the question

  • Thinking the default port is 80 (it's 8080)
  • Saying context-path defaults to `/api` or some non-empty value
  • Confusing context-path with a reverse-proxy prefix and double-prefixing
  • Believing `server.port=0` means 'no port' rather than 'random port'

context

resolving links…