Best practices for managing environment variables in Symfony Docker projects

[Bryce-Colton]

I'm currently working on a Symfony project that utilizes Docker, and I'm seeking clarification on the best practices for managing environment variables.

Symfony's documentation typically recommends using .env files for easier local configuration and variable overriding. Given this, is it still advisable to include all environment variables directly in the docker-compose.yml file, or should I primarily rely on .env files?

As a personal remark, I've noticed that new team members often default to adding new variables to the .env file, which leads to confusion when I explain that they should be defined in the docker-compose.yml instead.

What are the advantages and disadvantages of each approach in a Dockerized Symfony application, and how can we maintain a clean and efficient configuration?

Thank you!

[bzoks]

I think it should mostly depend on how you manage your app across different environments (dev, stage, prod,...).
If you use environment variables as per Symfony best practices, then you have only versionable/commitable things as ENV vars (various hostnames,...) and all secrets in config/secrets (with decryption key coming into the picture as docker secret).
This way, it is easy to have full set of all values for all envs in .env.dev, .env.stage, .env.prod, .env.sandbox,... and your docker-compose just sets (or forwards) env var APP_ENV. This makes sense if you have/use docker-compose also in non-dev envs.
Benefit of this is that then you can easily review vars for all envs (bin/console debug:dotenv --env stage). There is also no need for too many differences in docker-compose files (when they need to be env-specific), as maintaning them is somewhat more time consuming or less "natural" for PHP developers.
This approach does not block you from still using some env vars as overrides from docker-compose, for example if it can happen that some var changes outside of the usual development flow (like frequent password changes for some service, without the need for redeploy, just restart with new env var value).
In one of our apps, we for example generate .env file on-the-fly in our CI/CD and use that .env file as env-file property in docker-compose yaml to get (persistent) values that override internal (inside the image) .env.stage, for example setting DB_NAME to stage1, stage2, stage3,... as we have multiple versions and installations of same app on single server.

[Bryce-Colton]

Thank you for this detailed response; I really appreciate it.

I will remember a few simple principles:

• By default, all environment variables will be placed in the .env.APP_ENV file, unless they represent a secret.
• The docker-compose file will only contain APP_ENV and generated secrets.
• This docker-compose file will be generated during deployment.
• If necessary, certain variables can be overridden by the docker-compose file.

[necobm]

As said @bzoks , it's a better and easy to maintain approach keeping all your env vars inside .env.{your_environment} files, and only override APP_ENV or some other specific env vars directly in docker-compose.yaml.

I also use the approach that in deploy time, override .env with correct env vars, depending on environment (we have local, test, stage and prod), and, in our pipeline scripts, we have an .env file for each environment and "inject" the corresponding .env file in env-file property in docker-compose, as @bzoks do as well.

Take into account that is very recommended that you handle sensitive env vars like DB credentials or API Keys with a secret vault or something similar.

[Bryce-Colton]

Thank you for confirming the approach to take regarding environment variable management.