[💡 FEATURE REQUEST]: Support optional configuration files in include

[MihailDev]

Plugin

Config

I have an idea!

Problem

RoadRunner supports merging multiple configuration files using the include section:

include:
  - .rr.local.yaml

However, all included files are currently required. If .rr.local.yaml does not exist, RoadRunner fails to start:

handle_serve_command:
config_plugin_init: open .rr.local.yaml: no such file or directory

This makes it difficult to use local configuration overrides.

A common project structure is:

.rr.yaml # Base configuration committed to Git
.rr.local.yaml # Optional developer-specific configuration ignored by Git

The base configuration should work without requiring every developer, CI environment, or production deployment to create an empty .rr.local.yaml file.

Proposed solution

Support an extended include syntax with an optional flag:

include:
  - file: .rr.local.yaml
    optional: true

When optional is true:

If the file exists, RoadRunner loads and merges it normally.
If the file does not exist, RoadRunner skips it without failing.
Other errors, such as invalid YAML or insufficient permissions, should still produce an error.

Required includes could use:

include:
  - file: .rr.common.yaml
    optional: false

The existing scalar syntax should remain supported for backward compatibility:

include:
  - .rr.common.yaml

It could be treated as equivalent to:

include:
  - file: .rr.common.yaml
    optional: false

Example
version: "3"

include:
  - file: .rr.common.yaml
  - file: .rr.local.yaml
    optional: true

This would provide native support for developer-specific configuration overrides without requiring wrapper scripts, Makefiles, Docker entrypoints, or placeholder files.

[rustatian]

Hey @MihailDev 👋🏻 Thank you for the feature request. I have a questions: why are you using dev config in the CI env or production deployment as you said?

[rustatian]

This would provide native support for developer-specific configuration overrides without requiring wrapper scripts, Makefiles, Docker entrypoints, or placeholder files.

Not sure about that. For the docker - use mounts to mount .rr.yaml for any env. Symlinks if needed. Currently, I don't understand the problem. If you have separate envs - please, use separate configurations for that.
Could you please give me an example, where that is reasonable to have this option?

[MihailDev]

Hi @rustatian

Thanks, let me clarify the actual use case.

We have the following configuration structure:

.rr.base.yaml   # common configuration
.rr.dev.yaml    # shared development configuration
.rr.prod.yaml   # production-only configuration
.rr.yaml        # default development entry point

# .rr.yaml
include:
  - .rr.base.yaml
  - .rr.dev.yaml

Part of the team runs the application directly on the host, while another part works through Docker.

For Docker-based development, the shared .rr.yaml works as-is. For host-based development, some values differ:

• exposed ports;
• addresses of local services;
• occasionally enabled or disabled services;
• machine-specific paths or sockets.

I would like to keep the same simple native command for both workflows: rr

The desired setup would be:

include:
  - file: .rr.base.yaml
  - file: .rr.dev.yaml
  - file: .rr.local.yaml
    optional: true

.rr.local.yaml would be ignored by Git and created only by developers who need host-specific overrides.

Without optional includes, the alternatives are:

• require every developer and Docker environment to have an empty placeholder file;
• use aliases or wrapper scripts;
• pass additional config options on every RoadRunner command.

An alias solves only the main start command partially, but RoadRunner has multiple commands, so the extra configuration argument must be repeated consistently for every command.

The proposal is not about mixing production and development configurations. It is about adding an optional machine-specific overlay while keeping .rr.yaml as the shared development entry point and preserving the standard rr command.

Another possible solution would be to allow specifying a dotenv file directly in the RoadRunner configuration:

env_file: .env

This would allow each developer to keep their local values in a Git-ignored .env file while continuing to use standard RoadRunner commands

[rustatian]

RoadRunner supports dotenv files: https://docs.roadrunner.dev/docs/php-worker/environment#dotenv

[MihailDev]

RoadRunner supports dotenv files: https://docs.roadrunner.dev/docs/php-worker/environment#dotenv

Yes, I know RoadRunner supports dotenv files through the CLI.

The inconvenience is that the dotenv file must be specified in every command, for example:

rr serve --dotenv .env
rr reset --dotenv .env
rr workers --dotenv .env

I would like to configure the dotenv file once inside .rr.yaml

env_file: .env

[rustatian]

Yeah, not very convenient to use dotenv like that. The env option looks better to me than that optional proposal in the includes.
Will that help you?

[MihailDev]

Yes, that would solve my problem.

If RoadRunner could always load the dotenv file automatically based on the configuration, without requiring --dotenv in the command, that would be enough for my use case.