CLI Support for Non-Default and Merged docker compose files

General
1

I wanted to restart a discussion on balena-cli supporting non-default docker-compose.yml files.

Background

For context, docker compose allows changing and merging the docker-compose filename using the -f flag: docker compose | Docker Docs
This allows for two workflows:

  • Specifying multiple docker-compose files which are merged in order
  • Specifying a single docker-compose file in a different path

Use Cases

First, to allow multiple fleets with different feature subsets to be deployed from the same source code. For example, we have two robots that are identical except that one runs computer vision on a Jetson and one does not.

We’d like to push layered files that build the config this way:

docker-compose.yml         # Default, for local dev
docker-compose.prod.yml    # Deployed to Balena
docker-compose.mod-cv.yml  # Module which adds CV containers

The CV fleet would receive balena push -f docker-compose.prod.yml -f docker-compose.mod-cv.yml.

The non-CV fleet would receive balena push -f docker-compose.prod.yml.

Second, this change would allow docker-compose.yml to be used for local development.

Since this is the default file for docker compose, it improves developer ergonomics to have this file be configured to spin up a local environment. Compose files for Balena often have a lot of config specific to the production devices that you don’t want to run locally.

I’d guess for most teams running your code locally is >100x more frequent than pushing a release, so this workflow should be as simple as possible (docker compose up).

Proposed Solution

My proposed solution is that balena-cli should take in one or more -f / --filename arguments, specifying one or more compose files:

-f, --filename<value>
  Provide one or more alternative Compose files. Files will be merged in order.

This behavior should match docker compose, and will allow users to change the compose filename and merge multiple compose files.

In addition, Add support for docker-compose dev overlay by srlowe · Pull Request #2177 · balena-io/balena-cli · GitHub would be replaced by this functionality. users who want the docker-compose.dev.yml functionality would use balena push -f docker-compose.yml -f docker-compose.dev.yml to match compose’s syntax for multiple files.

References

I’ve created a Balena Feature Request for this: CLI Support for Non-Default or Multiple Compose files · Balena Feature Requests

Long-running request (since 2019): Add ability to select a docker-compose file · Issue #1142 · balena-io/balena-cli · GitHub

PR from April which is an attempt to add this: Feat: Add ability to select a docker-compose file by quentingllmt · Pull Request #2760 · balena-io/balena-cli · GitHub