Maven Properties, Profiles, settings.xml, Mirrors, Proxies, Servers, and Environment-Specific Builds: Concepts, Architecture, and Mental Model

1. The practical problem — one POM, many environments

Chapters 04–07 made Maven itself, the POM, dependencies, lifecycle, and plugins visible. A production build still has another source of state: the environment that invokes the project. Developer laptops, CI agents, and controlled release workers may need different proxy routes, mirror endpoints, authentication material, or explicitly selected build modes. If those differences leak into the POM, the project becomes machine-specific. If they remain hidden in uninspected settings, the build becomes difficult to reproduce.

The goal is not “make every machine identical.” The goal is to establish a contract: portable build intent stays with the project; access policy and secrets stay at controlled environment boundaries; every effective difference is observable.

2. The state stores must remain separate

Maven combines several inputs during model building and repository resolution, but combining them at runtime does not make them the same kind of state.

3. Mental model — declared project + environment policy → effective build

Maven first establishes runtime/system/user properties and settings, builds the effective project model with active profiles, and then resolves repositories after mirror/proxy/server policy is applied. This is why a repository URL written in a POM is not necessarily the network endpoint contacted by the build.

flowchart TD
  POM[pom.xml + project profiles]
  MVN[.mvn wrapper/config]
  GS[global settings.xml]
  US[user/alternate settings.xml]
  ENV[system + env + CLI user properties]
  EFF[effective POM + active profiles]
  SET[effective settings]
  REPO[declared repository IDs]
  MIR[mirror/proxy/server policy]
  END[actual endpoint]
  POM --> EFF
  MVN --> EFF
  GS --> SET
  US --> SET
  ENV --> EFF
  ENV --> SET
  SET --> EFF
  EFF --> REPO
  SET --> MIR
  REPO --> MIR
  MIR --> END

Every arrow represents a causal relationship you can inspect: settings change the effective environment, active profiles change the effective POM, and mirrors rewrite repository routing before transport begins.

4. Property sources — name the source before arguing about “precedence”

Maven exposes several property families. ${project.version} comes from the project model; ${settings.offline} comes from settings; ${java.home} is a Java system property; ${env.PATH} exposes an environment variable; plain ${academy.channel} may come from POM/profile properties or from a command-line user property such as -Dacademy.channel=cli.

5. Profiles are conditional model fragments, not “environments” by themselves

A profile can contribute properties, dependencies, repositories, plugin configuration, and other model elements. Profiles may live in the project POM, user settings, or global settings. Maven resolves profile activation early; profile effects participate in the effective model. A child does not simply inherit the parent's raw profile definition as another switch.

6. What belongs in settings.xml

Maven merges global and user settings, with user settings dominant where the models overlap. An alternate user settings file may be selected with -s/--settings; an alternate global settings file uses -gs/--global-settings. These are invocation/environment controls, not POM content.

7. Mirrors, repository IDs, and server credential indirection

A mirror does not “add another repository.” It substitutes the endpoint Maven uses for repositories matched by mirrorOf. The mirror has its own id. Maven's settings documentation explicitly states that this mirror ID is used to pick corresponding credentials from <servers>. That is why changing only a server ID can turn a working build into a 401 even when username/password values did not change.

<mirrors>
  <mirror>
    <id>corp-mirror</id>
    <url>https://repo.example.invalid/maven-virtual</url>
    <mirrorOf>external:*</mirrorOf>
  </mirror>
</mirrors>
<servers>
  <server>
    <id>corp-mirror</id>
    <username>${env.REPO_USER}</username>
    <password>${env.REPO_PASSWORD}</password>
  </server>
</servers>

Patterns include exact repository IDs, *, external:*, external:http:*, comma-separated expressions, and ! exclusions. Broader is not automatically safer: * can capture a repository that a test fixture expected to remain local.

8. Proxy state is transport policy, not dependency identity

A proxy controls how Maven reaches an endpoint; it does not change a coordinate such as org.example:lib:1.2.3. Keep this distinction during diagnosis. A 407 proxy-authentication error is not evidence that the dependency version is wrong. Likewise, adding a new repository to “fix networking” changes the supply-chain boundary and is not a harmless network workaround.

9. Read-only inspection before mutation

Use the wrapper and explicit Help Plugin version. Write evidence outside target/ so a later clean does not erase it.

mkdir -p evidence
./mvnw -v | tee evidence/maven-version.txt
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:active-profiles   -Doutput=evidence/active-profiles.txt
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:effective-settings   -Doutput=evidence/effective-settings.xml
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:effective-pom   -Dverbose -Doutput=evidence/effective-pom.xml
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:evaluate   -Dexpression=academy.channel -q -DforceStdout

10. DevOps operating contract

A robust CI job records wrapper/Maven/JDK identity, the explicit profile selection, the settings source/policy identifier, and the repository/mirror endpoint IDs without printing secrets. The artifact pipeline should be able to answer: Which profile changed the model? Which settings selected the network path? Which server ID supplied authentication? Which properties were invocation overrides?

11. Common misconceptions

Knowledge check

12. Summary and bridge

Chapter 08 starts by making the environment boundary explicit: POM and project wrapper/config are repository-owned build intent; settings, proxy/mirror/server credentials, process environment, and caches are controlled execution context. The effective model is the evidence that joins them. Lesson 2 now builds a safe local fixture so each layer can be observed rather than merely described.

Official references and version notes

Version-sensitive statements in this lesson were checked against Apache Maven primary documentation on 2026-08-23. The mandatory path uses Maven 3.9.16 through Maven Wrapper 3.3.4, JDK 21 to run Maven, Java 17 as the project release target, Help Plugin 3.5.2, Dependency Plugin 3.11.0, Compiler Plugin 3.15.0, Resources Plugin 3.5.0, Surefire 3.5.6, and JAR Plugin 3.5.1. Maven 4-only profile syntax and preview behavior are not required here.

• Maven — Settings Reference
• Maven — Introduction to Build Profiles
• Maven — POM Reference / Properties
• Maven — Using Mirrors for Repositories
• Maven — Setting up Multiple Repositories
• Maven — Security and Deployment Settings
• Maven — Injecting POM Properties via settings.xml
• Maven Help Plugin 3.5.2
• Maven Dependency Plugin 3.11.0
• Maven Compiler Plugin 3.15.0
• Maven JAR Plugin 3.5.1
• Maven Resources Plugin 3.5.0
• Maven Surefire 3.5.6
• Apache Maven Wrapper
• Maven 3.9.16 Release Notes