CicloUrbana is full of hard-coded numbers: 0.50 to unlock, 0.12 per minute, 15 free minutes for students, a minimum of 8 docks per station. Changing any of them today demands a recompile and a redeployment. That is not acceptable: Ribalta city council changes its fares every season, and the server port is not the same on your laptop as on the production server. The answer is to externalise the configuration, and Spring Boot has one of the most complete —and most misunderstood— mechanisms for that in the Java ecosystem. In this lesson we will look at what the Environment is and where it gets its values from, the exact order of precedence between sources, the real differences between .properties and .yaml, how Spring relaxes property names so that CICLOURBANA_BASEFARE and ciclourbana.base-fare are the same thing, how to read values with @Value, and why a credential must never live in the repository.

1. The Environment and the PropertySources
2. The order of precedence of the sources
3. Demonstrating precedence in practice
4. .properties versus .yaml
5. Relaxed binding
6. Reading properties with @Value
7. SpEL and default values
8. The properties CicloUrbana uses
9. External configuration: spring.config.import and spring.config.location
10. Secrets and credentials
11. Common Mistakes and Tips
12. Exercises

In lesson 01-05 we saw that one of the first startup phases is "preparing the Environment". Now we can pin down what that means.

The Environment is a Spring bean that answers two questions: what is the value of this property? and which profiles are active? (profiles are covered in lesson 07-02). Internally it stores no values at all: it keeps an ordered list of PropertySources and, when you ask it for a key, it walks them in order and returns the first one that holds it.

The consequence is fundamental: the first one to answer wins. All of Spring Boot's precedence logic boils down to the order in which the PropertySources are placed in that list.

You can inspect the full list in your own application:

Typical output in CicloUrbana:

This ConfigurationInspector is a tool worth keeping to hand: when a property "is not being read", the first thing to do is see which source is winning it.

Spring Boot defines a complete, documented order. From highest to lowest priority, keeping to what matters in practice:

Three rules that sum the table up and are worth memorising:

1. The most external wins. The closer to the moment of startup a value is specified, the higher its priority. A --server.port=9090 on the command line beats any file.
2. Outside the jar beats inside the jar. That is what lets you package sensible defaults and have the operator adjust them without rebuilding anything.
3. With a profile beats without one. application-prod.properties overrides application.properties.

The three rows you will use 95% of the time are 3 (arguments), 8 (environment variables) and 12 (the project's application.properties). The rest are worth knowing so you are never taken by surprise.

Nothing convinces like seeing it work. Let us start with the project file:

Start it normally:

Now override it with an environment variable (row 8):

Now with a system property (row 7, which beats the environment variable):

And finally with a command-line argument (row 3, the one that beats them all):

Note the syntactic difference, which confuses a lot of people:

Putting --server.port=9090 before -jar does not work: the JVM would read it as one of its own options and fail. And -Dserver.port after the jar arrives as just another application argument, which Spring does not recognise as a property.

With Maven, passing arguments requires the plugin's own property:

Spring Boot accepts both formats, with the same capabilities. The choice is a matter of style... until the structure grows.

The same CicloUrbana configuration in both formats:

Side by side:

Practical recommendation: pick one and be consistent. If your configuration is flat and short, .properties is harder to break. As soon as lists, maps and three levels of nesting appear —CicloUrbana's case as soon as we reach lesson 02-05— YAML is clearly more readable. From here on this course uses YAML.

Never keep both files at once: application.properties wins, and you will spend an entire afternoon wondering why your YAML is not being read.

They are the price of the format, and every one of them is silent: the file is read, but the properties end up somewhere else.

The first case produces a clear startup error (server does not accept a scalar value), but subtler variants simply leave the property orphaned and the application starts with the default value. Rule: two spaces per level, never tabs, and turn on invisible-character display in your IDE.

Spring Boot does not require the property name to be spelled exactly the same everywhere. It applies a relaxation algorithm that treats several forms as equivalent:

All four resolve to the same property. This is what lets you write, in a docker-compose.yml or in a Kubernetes Deployment:

and have those values reach ciclourbana.fare.unlock, ciclourbana.network.minimumCapacity and server.port.

The rules for turning a property into an environment variable are three:

1. Dots (.) become underscores (_).
2. Hyphens (-) are removed.
3. Everything in uppercase.

So ciclourbana.network.minimum-capacity → CICLOURBANA_NETWORK_MINIMUMCAPACITY. That second point is the one that causes the most headaches: many people write CICLOURBANA_NETWORK_MINIMUM_CAPACITY and it does not work, because that name would correspond to ciclourbana.network.minimum.capacity, with one dot too many.

Two important limitations of relaxation:

• It only applies to @ConfigurationProperties binding (lesson 02-05) and to Spring Boot's own properties. With @Value the match is exact: @Value("${ciclourbana.base-fare}") will not find a property written ciclourbana.baseFare.
• Map keys are not relaxed: if you define ciclourbana.fares-by-user.grant-student, the map key will be literally grant-student.

Recommended convention: always write kebab-case in files. It is the canonical form, the one that appears in the Spring Boot documentation and the one that avoids ambiguity.

@Value injects a property's value into a field or a parameter. Let us finally pull StandardFare's prices out of its constants:

Notice that @Value goes on the constructor parameters, not on the fields. That way the fields stay final and the class remains buildable in a test with new StandardFare(new BigDecimal("0.50"), new BigDecimal("0.12")), with no Spring in the way. It is the same reasoning as lesson 02-02, applied to configuration.

Spring converts the text to the parameter's type automatically:

For List<String> to work with @Value, the value must be a comma-separated string, not a YAML list:

This is already the first crack in @Value, and it will not be the last.

If a property does not exist, @Value fails at startup:

You avoid that with the ${key:defaultValue} syntax:

Watch out for one special case: if the default value contains a : (a URL, for instance), bear in mind that only the first : counts as the separator, so @Value("${url:http://localhost:8080}") works correctly and the default value is the complete URL.

@Value also accepts SpEL expressions with the #{...} syntax (hash, not dollar):

And one that really is practical: random values, for ports or identifiers in tests.

@Value is convenient for one or two loose values, but it falls short as soon as the configuration grows. Its problems:

@ConfigurationProperties solves all of them, and it is the subject of the next lesson. The rule we will apply in CicloUrbana: @Value for isolated, occasional values; @ConfigurationProperties for everything else.

This is the project's base configuration, with each block explained:

The most useful server and application properties:

A warning about server.servlet.context-path: if you set it to /ciclourbana, our endpoint's URL becomes http://localhost:8080/ciclourbana/api/v1/stations. That change breaks every client and every .http file from lesson 01-02, so in CicloUrbana we will leave it at /.

Check that the configuration is applied:

Everything above lives inside the jar. A real deployment needs configuration that is not packaged.

Spring Boot looks for application.yaml automatically, in this order of priority, in:

1. ./config/ (a config subdirectory next to the jar)
2. ./ (the current directory)
3. classpath:/config/
4. classpath:/ (inside the jar)

In other words, leaving a file next to the jar is enough to override the packaged values:

This lets you include other files from the main configuration. It is the modern, preferred alternative to @PropertySource:

The optional: prefix is crucial: without it, if the file does not exist the startup fails. There is logic to that —you want to know when an indispensable file is missing— but in development it is inconvenient, which is why files belonging to one specific environment are almost always marked optional.

spring.config.import accepts other origins too:

The configtree: format deserves a note: in Kubernetes and Docker Swarm, secrets are mounted as files, one per key, inside a directory. With configtree: Spring Boot reads that tree and turns each file into a property. It is the idiomatic mechanism for secrets in containers, and we will come back to it in lesson 07-04.

This replaces the default locations entirely, rather than adding to them:

And spring.config.additional-location adds locations while keeping the defaults, which is usually what you actually want:

This section is not optional. It is the part of the lesson with the most serious consequences if ignored.

Never, under any circumstances, write passwords, API keys, tokens or certificates in a file that goes into the code repository.

What you must not do, even though you will see it in tutorials:

Why it is so serious, beyond the obvious:

• Git does not forget. Deleting the line in a later commit does not remove the secret: it is still in the history, reachable with git log -p. Rotating the credential is mandatory, not optional.
• Repositories get copied. Forks, clones on laptops, backups, CI integrations, an intern's computer. A secret in Git is, in practice, in many more places than you think.
• Repositories change visibility. A private repository that is made public leaks its entire history in one go. It is a surprisingly frequent accident.
• Bots crawl. There are bots scanning GitHub for key patterns; a cloud provider's key published by mistake is exploited within minutes.

What to do instead:

1. Environment variables with a placeholder and no default value. The versioned file declares what it needs, not what it is worth:

Note the detail: the gateway key has no default value. If someone deploys without defining it, the startup fails immediately with a clear message. That is far better than starting up and failing on the first payment.

2. An external file outside the project tree, with restricted permissions:

3. A secrets manager, which is the right answer in serious production: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault or Kubernetes Secrets mounted as configtree:. They are covered in module 8.

4. Protect the repository. Add any local secrets file to .gitignore and consider a pre-commit hook that detects suspicious patterns:

5. If a secret leaks, rotate it. Do not just delete it from the file and carry on. Invalidate the credential and issue a new one. It is the only action that genuinely closes the hole.

One final note: in lesson 02-05 we will also see how to stop a secret ending up accidentally in the logs, and in module 7, how Actuator hides sensitive values in the /actuator/env endpoint.

Having application.properties and application.yaml at the same time. The .properties wins and the YAML looks ignored. Delete one.

Spelling the environment variable's name wrongly. CICLOURBANA_NETWORK_MINIMUM_CAPACITY is not ciclourbana.network.minimum-capacity: hyphens are removed, not turned into underscores. The correct name is CICLOURBANA_NETWORK_MINIMUMCAPACITY.

Using tabs in YAML. The file is rejected with a parse error that does not always point at the right line. Configure your editor to insert spaces.

Putting --server.port before the -jar. The JVM does not understand it. The -- ones go after the jar; the -D ones go before.

Expecting relaxed binding with @Value. There is none. With @Value the key must match character for character.

Confusing ${...} with #{...}. The first resolves properties; the second evaluates SpEL. @Value("#{ciclourbana.city}") tries to evaluate ciclourbana.city as an expression and fails; the correct form is ${ciclourbana.city}.

Putting a password in application.yaml. Repeated on purpose: it is the most expensive mistake in this lesson.

Tip: name your properties with a prefix of your own. Everything in CicloUrbana starts with ciclourbana.. That way you never clash with a Spring Boot or library property, and grep -r "ciclourbana\." src/ tells you at a glance what configures the application.

Tip: use server.port=0 in tests. It assigns a free port and avoids failures when two tests run at the same time. We will come back to it in module 6.

Tip: document each property with a comment. Whoever deploys your application a year from now will thank you, and they will not need to read the code to find out whether battery-threshold is a percentage or a voltage.

Tip: in development, do not depend on the command line. An application-dev.yaml with a profile (lesson 07-02) is more reproducible than a long command that only exists in your memory.

Define ciclourbana.city=Ribalta in application.yaml. Write a CityNotice component that logs its value at startup. Then start the application four times —plain, with an environment variable, with a system property and with a command-line argument— giving a different value each time, and note which one wins. Add to the component a dump of the source that supplied the value.

StudentFare still has its constants hard-coded. Externalise them to ciclourbana.fare.student.price-per-minute and ciclourbana.fare.student.free-minutes, with default values in the @Value itself so that the application starts even if they are missing. Verify that the amount of a 45-minute rental changes when you override the properties from the command line.

Prepare a realistic deployment: package the jar, create a config/ directory next to it with an application.yaml that changes the port to 9090, raises the unlock charge to €0.60 and reads the database password from an environment variable with no default value. Check that the application fails to start if the variable is undefined, and that it starts correctly when it is defined.

Solution 1

The four runs:

Comment: the winningSource() method implements the Environment algorithm described in section 1 literally —walk the ordered list and take the first match— and that is why its result always agrees with the injected value. It is a good diagnostic to keep to hand.

A note on the configurationProperties source that appears first in the listing: it is a synthetic source Spring Boot uses internally for binding; it supplies no values of its own.

Solution 2

Verification with the FareDemo from lesson 02-02:

Comment and a frequent mistake: if you write @Value("${ciclourbana.fare.student.freeMinutes:15}") —in camelCase— it will not bind to the file's free-minutes property: it will always take the default value of 15, silently and with no error at all. That is exactly the absence of relaxed binding from section 5, and it is one of the weighty reasons to move to @ConfigurationProperties in the next lesson.

Tip: notice that the prices are declared as BigDecimal, not as double. With money, double produces unacceptable rounding errors (0.1 + 0.2 is not 0.3). It is a rule that must never be broken in a domain that handles amounts.

Solution 3

First attempt, without the environment variable:

Second attempt, with it defined:

Comment: the failure on the first attempt is desirable. A placeholder with no default value turns a forgotten deployment step into an immediate, obvious error, instead of a silent failure at three in the morning when somebody tries to pay. It is the same "fail early and loudly" philosophy we saw with the eager creation of singletons in lesson 02-03.

A deployment tip: on a real server the password is not written on the command line —it would be visible in ps aux and in the shell history— but in the systemd unit file, in the corresponding EnvironmentFile with 600 permissions, or in the platform's secrets manager. In Docker it is passed as a container environment variable or, better, as a secret mounted as a file and read with configtree: (lesson 07-04).

CicloUrbana's configuration has left the code. You know that the Environment stores no values but an ordered list of PropertySources, and that all the precedence logic boils down to the order of that list: the most external wins, outside the jar beats inside, and with a profile beats without one. You have checked it yourself by starting the same application with a file, an environment variable, a system property and a command-line argument, and you can tell the three syntaxes apart. You know the real differences between .properties and YAML —and why the course uses YAML from here on— along with the indentation trap. You understand relaxed binding and the three rules that turn ciclourbana.network.minimum-capacity into CICLOURBANA_NETWORK_MINIMUMCAPACITY, including the removal of hyphens that breaks so many deployments. You know how to read properties with @Value, give them default values, use SpEL when it earns its place... and you also know the seven limitations that make @Value a tool for occasional use. You know how to import external configuration with spring.config.import and spring.config.additional-location. And, above all, you know that a credential never goes into the repository, why the damage is permanent and what the real alternatives are.

The Ribalta network's prices can now be changed without recompiling. But the solution has obvious cracks: the keys are scattered across several classes, a mistyped camelCase fails silently, nobody validates that the price per minute is positive, and the IDE gives no help writing the properties. The next lesson, Spring Boot Properties, fixes all four with @ConfigurationProperties: typed configuration, grouped into immutable objects, validated with Bean Validation, with automatic conversion of Duration and DataSize, and with autocompletion in the IDE. We will convert the whole fare and Ribalta network configuration to that form, which is the one the project will keep until the end of the course.