
# Profiles

A profile is a name for a situation the application runs in, such as `dev`, `test`, `prod` or `eu`. Activating a profile reads more config files and documents, and creates the beans meant for that situation. The rest of the setup stays shared.

## Why

Environments often differ by more than one or two values: another database, a fake payment service in development, other URLs per region. Profiles group these differences under one name, chosen at launch, so the code never asks "am I in production?".

## Example

```yaml
# lib/resources/application.yml
shop:
  payment: fake
  url: http://localhost:8080
spring:
  profiles:
    group:
      prod: [eu, monitoring]   # prod also activates eu and monitoring
```

```yaml
# lib/resources/application-prod.yml
shop:
  payment: stripe
  url: https://neon.books
```

```yaml
# lib/resources/application-eu.yml
shop:
  currency: EUR
```

```bash
dart run bin/main.dart --spring.profiles.active=prod
SPRING_PROFILES_ACTIVE=prod dart run bin/main.dart
flutter run --dart-define=SPRING_PROFILES_ACTIVE=prod
```

The start logs `The following 3 profiles are active: "prod", "eu", "monitoring"`, and `shop.payment` is `stripe`.

```dart
// A bean that exists only with the prod profile.
@Service()
@Profile(['prod'])
class StripePayments implements Payments { ... }
```

## Activating profiles

| Key | Type | Meaning |
|---|---|---|
| `spring.profiles.active` | comma list or YAML list | The active profiles. The first source that has the key wins, so the command line beats a file |
| `spring.profiles.include` | comma list or YAML list | Profiles added to the active ones, from every source |
| `spring.profiles.default` | comma list | The profiles used while none is active; `default` when not set |
| `spring.profiles.group.<name>` | list | Activating `<name>` activates these too. Groups can contain groups. `<name>` is matched exactly (`group.Prod` is no group of `prod`) |
| `spring.profiles.validate` | bool, default `true` | Checks the names: letters, digits and `-_.+@`, starting and ending with a letter or digit |

In code:

- `SpringApplication(additionalProfiles: ['mobile'])` activates profiles on every run, before the configured ones (so their files have the lowest precedence of the profile files).
- `run(args, additionalProfiles: [...])` adds profiles for one launch.
- `springBootTest(profiles: ['test'])` replaces `spring.profiles.active` in a test.

The order of activation: `additionalProfiles` first, then the profiles set in code, then `spring.profiles.active`, then `include`, each followed by its groups. With several active profiles, the files of the last one win.

## Profile files

For each active profile, `application-{profile}.yml` (or `.yaml`, `.properties`) is read in every location, after the plain file, so its values win. While no profile is active, the `default` profile (or those of `spring.profiles.default`) picks the files: `application-default.yml` is read then.

An imported file has profile variants too: when `application.yml` imports `local.yml`, `local-dev.yml` is read with `dev` and wins over `application-dev.yml`. See [Imports](imports.md).

## Documents for some profiles or platforms

Instead of a separate file, a document inside a file can be limited:

| Key | Meaning |
|---|---|
| `spring.config.activate.on-profile` | The document applies when this profile expression matches. A comma list means "any of". An empty value is no condition |
| `spring.config.activate.on-cloud-platform` | The document applies on this platform: `kubernetes`, `heroku`, `cloud-foundry`, `azure-app-service`, `amazon-ecs`, `nomad`, `sap`, or `none` (no platform) |

```yaml
shop:
  region: local
---
spring:
  config:
    activate:
      on-profile: "prod & !us"
shop:
  region: eu
---
spring:
  config:
    activate:
      on-cloud-platform: kubernetes
shop:
  region: cluster
```

```properties
shop.region=local
#---
spring.config.activate.on-profile=prod & !us
shop.region=eu
#---
spring.config.activate.on-cloud-platform=kubernetes
shop.region=cluster
```

The pre-2.4 key `spring.profiles` (as a document condition) is rejected; write `spring.config.activate.on-profile`.

## Profile expressions

| Expression | Matches when |
|---|---|
| `prod` | `prod` is active |
| `!prod` | `prod` is not active |
| `prod & eu` | both are active |
| `prod \| staging` | one of them is active |
| `prod & (eu \| us)` | parentheses group; `&` and `\|` cannot be mixed without them |
| `prod, staging` | a comma list: any of them |

The same expressions work in `@Profile`. Malformed expressions (`(dev`, `a &`, `a b`) fail the start with `Malformed profile expression`; Spring accepts some of them.

## Cloud platforms

The platform is detected from environment variables, as Spring Boot does it:

| Platform | Detected when these are set |
|---|---|
| `kubernetes` | `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` |
| `heroku` | `DYNO` |
| `cloud-foundry` | `VCAP_APPLICATION` or `VCAP_SERVICES` |
| `azure-app-service` | `WEBSITE_SITE_NAME`, `WEBSITE_INSTANCE_ID`, `WEBSITE_RESOURCE_GROUP` and `WEBSITE_SKU` |
| `amazon-ecs` | `ECS_CONTAINER_METADATA_URI` or `ECS_CONTAINER_METADATA_URI_V4` |
| `nomad` | `NOMAD_ALLOC_ID` |
| `sap` | `HC_LANDSCAPE` |

`spring.main.cloud-platform` forces a platform, or turns detection off with `none`. Beans use `@ConditionalOnCloudPlatform` (see [Conditions](../conditions.md)). The list forms (`on-cloud-platform[0]`) are ignored, as in Spring Boot.

## The rules that keep profiles stable

The profiles are decided before the profile files are read, as in Spring Boot, so those files cannot change them:

- A profile file (`application-dev.yml`, or `local-dev.yml` for an imported `local.yml`) may not set `spring.profiles.active`, `.default` or `.include`; the start fails with an `InvalidConfigDataPropertyException`. Its `spring.profiles.group.*` is ignored.
- A document limited to a profile, in a file read before the profiles are decided (`application.yml` and what it imports), may set none of the four keys; the start fails when the document applies.
- In a file read after the profiles are decided (imported by a profile file or an `on-profile` document), the four keys are ignored.

These keys are found under any spelling relaxed names allow: `spring.profiles.Active` in a profile file fails too.

## Profiles in Flutter apps

With `spring_boot_starter_flutter`, the platform is a profile as well: `android`, `ios`, `web`, `macos`, `windows` or `linux`, plus `mobile` (Android, iOS) or `desktop` (macOS, Windows, Linux). The build mode is one too, after the platform: `release`, `profile` or `debug`. So `application-ios.yml` and `application-release.yml` are read with no setup:

```yaml
# lib/resources/application-release.yml: a release logs only warnings
logging:
  level:
    root: warn
```

## In Spring (Java)

The same keys, files and expressions as Spring Boot 2.4 and later. Differences:

- `spring.profiles.active`, `.default` and `.group.*` in a document limited to a profile fail the start when the document applies, and are ignored when it does not (Spring Boot 4.1 reads them).
- Placeholders in `on-profile` are resolved once the profiles are decided, not at the first pass.
- A profile group written as a list with a gap is read up to the gap instead of failing.
- Profile expressions are stricter.

## See also

- [Profiles in spring_core_dart](../../spring-core-dart/config/profiles.md)
- [@Profile](../../spring-core-dart/beans/profile.md)
- [Config files](config-files.md)
- [Imports](imports.md)
- [Conditions](../conditions.md)
