Multiple Compose Files Template

A template repository from the balena solutions team demonstrating how to work with multiple Docker Compose files in balena projects.

Overview

This template provides a workaround for two key limitations in the balena CLI:

1. No --file flag support: The balena CLI doesn't support specifying which compose file to use (unlike standard Docker Compose)
2. No compose profiles support: Docker Compose profiles aren't currently supported in balena deployments

The target.sh script solves these issues by allowing you to maintain multiple compose files and select which one to deploy at build/push time.

Use Cases

This approach is particularly useful when you need to:

• Deploy different service configurations for different customers/vendors
• Maintain separate development, staging, and production compose files
• Switch between different hardware configurations
• Test various service combinations without modifying your main compose file

How It Works

The target.sh script:

1. Accepts a target compose file via the --file flag
2. Temporarily copies it to docker-compose.yml (the default file balena expects)
3. Executes the balena CLI command with your specified action and flags
4. Automatically cleans up the temporary file when done

This approach is safe and reliable—even if the script is interrupted, the cleanup trap ensures temporary files are removed.

Usage

Basic Syntax

./target.sh [build|push|deploy] --file <target-file> [balena-flags...]

Examples

Push to a fleet using vendor A's configuration:

./target.sh push --file compose.vendorA.yml my-fleet

Build locally with vendor B's configuration:

./target.sh build --file compose.vendorB.yml

Deploy with debug output:

./target.sh push --file compose.vendorC.yml my-fleet --debug

Deploy to a specific device:

./target.sh deploy --file compose.vendorA.yml my-device-uuid

Example Project Structure

An example project structure for 3 different vendors might look as follows:

.
├── compose.vendorA.yml           # Compose file for vendor A
├── compose.vendorB.yml           # Compose file for vendor B
├── compose.vendorC.yml           # Compose file for vendor C
├── target.sh                     # Helper script for multi-file deployment
├── service-authenticator/        # Authentication service
├── service-ui/                   # User interface service
├── service-vendorAspecific/      # Vendor-specific service
└── service-webserver/            # Web server service

Getting Started

1. Copy target.sh into your repo

2. Make the script executable:

   chmod +x target.sh

3. Create your compose files:

   • Edit compose.vendorA.yml, compose.vendorB.yml, etc. to define your service configurations
   • Each compose file can include different services, environment variables, or configurations

4. Deploy to your balena fleet:

   ./target.sh push --file compose.vendorA.yml <your-fleet-name>

Important Notes

• Never commit docker-compose.yml: This file is temporary and automatically managed by target.sh. Add it to your .gitignore if not already present.
• Balena CLI required: You must have the balena CLI installed and be logged in.
• File validation: The script validates that your target compose file exists before attempting deployment.
• Automatic cleanup: The script uses a trap to ensure temporary files are cleaned up even if interrupted.

Tips

• Version control: Keep all your compose variants in version control to track configuration changes
• Naming convention: Use descriptive names for your compose files (e.g., compose.production.yml, compose.customer-acme.yml)
• Testing: Always test with build locally before pushing to a fleet
• Documentation: Document the differences between your compose files in comments or separate docs

Limitations

• This is a workaround, not a native feature—if balena CLI adds --file or profile support in the future, consider migrating
• Each deployment requires explicitly specifying the target file
• The temporary docker-compose.yml file could cause confusion if the script is interrupted (though cleanup should handle this)

Support

For issues related to:

• This template: Open an issue in this repository
• Balena CLI: Visit the balena CLI repository
• Balena platform: Check the balena forums