Complete documentation for the Flutter DevContainer development environment.

FlutterBench follows the layered workBenches model:

• Layer 0: workbench-base:latest
• Layer 1a: dev-bench-base:latest
• Layer 2: flutter-bench:latest (bench-specific tools)
• Layer 3: flutter-bench:{user} (user image built from Layer 2)

Legacy monolithic .devcontainer/ Dockerfiles are deprecated and kept only for historical reference.

# Inspect the Flutter bench image chain
./scripts/rebuild-stack.sh --check

# Rebuild flutter-bench:latest and flutter-bench:${USER}
./scripts/build-layer.sh

# Start the bench container from the user image
./scripts/start-monster.sh

This documentation covers the FlutterBench system - the template and infrastructure for Flutter development with DevContainers.

• Template Maintainers: Updating and improving the Flutter DevContainer template
• System Administrators: Setting up shared infrastructure
• Advanced Users: Understanding the architecture and customization options

If you're working on a specific Flutter project using this template:

• See .devcontainer/docs/ in your project folder
• Start with .devcontainer/docs/README.md for quick start guides

env-file-docker-compose-guide.md
Complete guide to environment variables and Docker Compose configuration

• How .env files work with Docker Compose
• Complete variable reference (v2.0.0)
• Configuration examples and best practices
• Debugging and troubleshooting

template-configuration-guide.md
Template configuration architecture and philosophy

• Centralized configuration via .env
• Container naming system
• Variable flow and lifecycle
• File structure and responsibilities

flutter-infrastructure-architecture.md
System architecture and design

• Shared ADB infrastructure design
• Network topology (dartnet)
• Communication flow diagrams
• Lifecycle management

infrastructure-qa-and-setup.md
Q&A and setup clarifications

• Common setup questions answered
• Infrastructure configuration
• Template usage instructions
• Path verification

vscode-tasks-snippets.md
VS Code configuration and code snippets

• Complete tasks.json for Flutter projects
• DevContainer.json templates
• Docker-compose.yml examples
• Layered image build examples (Dockerfile.layer2)
• Shell script snippets

path-pinning-verification.md
Path resolution and verification

• Relative path strategy
• Path calculation formulas
• Verification procedures
• Troubleshooting path issues

document-index.md
Master index of all documentation

• Document set overview
• Quick navigation guide
• Implementation phases
• Key concepts summary

CONTAINER_COMPARISON.md
Comparison of container approaches

• FlutterBench vs Project containers
• Use case recommendations

PROJECT_IMPLEMENTATION_SUMMARY.md
Historical implementation summary

• Project evolution
• Implementation decisions
• Lessons learned

Creating a New Project:

cd /home/brett/projects/workBenches/devBenches/flutterBench/scripts
./new-flutter-project.sh myproject ../../Dartwingers

Updating an Existing Project:

cd /home/brett/projects/workBenches/devBenches/flutterBench/scripts
./update-flutter-project.sh /path/to/project

1. Update template files in templates/flutter-devcontainer-template/
2. Increment version numbers in:
   • Dockerfile.layer2 (version labels, if present)
   • .devcontainer/docker-compose.yml (version comments)
   • .devcontainer/.env.base (version header)
3. Test template with new-flutter-project.sh
4. Update documentation as needed

What: Single ADB server container shared by all Flutter projects
Why: Eliminates port 5037 conflicts, consistent device connections
Where: infrastructure/mobile/android/adb/

What: All project configuration in .devcontainer/.env file
Why: Never modify template files, perfect reusability
How: Docker Compose substitutes ${VARIABLES} from .env

Bench Level: System-wide templates and infrastructure
Project Level: Individual Flutter project containers

Philosophy:

• FlutterBench = Heavy development workbench
• Project containers = Lightweight debugging/running

flutterBench/
├── docs/                           # THIS DIRECTORY - System documentation
│   ├── README.md                   # This file
│   ├── env-file-docker-compose-guide.md
│   ├── template-configuration-guide.md
│   ├── flutter-infrastructure-architecture.md
│   ├── infrastructure-qa-and-setup.md
│   ├── vscode-tasks-snippets.md
│   ├── path-pinning-verification.md
│   ├── document-index.md
│   ├── CONTAINER_COMPARISON.md
│   └── PROJECT_IMPLEMENTATION_SUMMARY.md
│
├── templates/
│   └── flutter-devcontainer-template/
│       ├── .devcontainer/
│       │   ├── devcontainer.json
│       │   ├── docker-compose.yml
│       │   ├── Dockerfile
│       │   ├── .env.base            # v2.0.0 template
│       │   ├── docs/               # Project-level docs
│       │   ├── scripts/            # Startup scripts
│       │   └── adb-service/        # ADB configuration
│       ├── .vscode/
│       ├── .github/
│       └── scripts/
│
└── scripts/
    ├── new-flutter-project.sh      # Create new projects
    ├── update-flutter-project.sh   # Update existing projects
    └── new-dartwing-project.sh     # Create Dartwing projects

• Centralized .env configuration: All settings in .devcontainer/.env
• .devcontainer organization: All Docker files in .devcontainer/ folder
• Dynamic user configuration: Use $(whoami), $(id -u), $(id -g)
• Comprehensive variables: Added COMPOSE_PROJECT_NAME, ADB_INFRASTRUCTURE_PROJECT_NAME, etc.
• Documentation restructuring: Consolidated and organized all docs

• Initial shared ADB infrastructure
• Template-based project creation
• Basic environment variable support

After modifying any file in templates/flutter-devcontainer-template/:

1. Increment version numbers (follow rule: hLPRgFHb5Y0f9ulTfGtfm8)
2. Test the template:

   cd scripts
   ./new-flutter-project.sh test-project /tmp
   cd /tmp/test-project
   code .
   # Test in container

3. Update existing projects (optional):

   ./update-flutter-project.sh /path/to/existing/project

1. Add to .devcontainer/.env.base with documentation
2. Use in docker-compose.yml: ${NEW_VARIABLE:-default}
3. Update documentation: env-file-docker-compose-guide.md
4. Increment version numbers
5. Test with new project

1. Update infrastructure files in infrastructure/ (outside flutterBench)
2. Test with existing projects
3. Document changes in relevant docs
4. Notify project maintainers if breaking changes

• Bench-level documentation - This directory
• Template - DevContainer template
• Scripts - Project creation and update scripts

• VS Code DevContainers
• Docker Compose Documentation
• Flutter Documentation

1. Follow existing structure and naming conventions
2. Update version numbers in modified files
3. Test examples before documenting
4. Keep README.md updated with new files

1. Test thoroughly before committing
2. Increment version numbers per rules
3. Update related documentation
4. Maintain backward compatibility when possible

Last Updated: October 2025
Version: 2.0.0
Maintained by: FlutterBench Team