https://github.com/opensoft/flutterbench
This is a devcontainer setup for Flutter development. Scripts for setting up new devcontainer projects with well manered containers.
https://github.com/opensoft/flutterbench
Last synced: 12 days ago
JSON representation
This is a devcontainer setup for Flutter development. Scripts for setting up new devcontainer projects with well manered containers.
- Host: GitHub
- URL: https://github.com/opensoft/flutterbench
- Owner: opensoft
- Created: 2025-10-04T21:28:13.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T20:19:04.000Z (about 1 month ago)
- Last Synced: 2026-05-27T22:12:57.469Z (about 1 month ago)
- Language: Shell
- Size: 501 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 FlutterBench - Flutter Development Environment
A comprehensive Flutter development environment with DevContainer templates and project creation tools.
## 🧱 Container Architecture (Layered)
FlutterBench is standardizing on 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 Note
Any monolithic `.devcontainer/` Dockerfiles are **deprecated**. The layered images are the source of truth going forward.
## Bench Image Workflow
Use these commands for the bench itself:
```bash
# Check whether Flutter bench images are current
./scripts/rebuild-stack.sh --check
# Rebuild Layer 2 and Layer 3
./scripts/build-layer.sh
# Start the bench container from the prebuilt user image
./scripts/start-monster.sh
```
`./scripts/start-monster.sh` no longer builds a monolithic devcontainer image. It ensures `flutter-bench:latest` exists, refreshes `flutter-bench:${USER}` if needed, and then starts the bench container from the layered image.
## Flutter SDK policy
`flutterBench` now carries two SDK tracks in Layer 2:
- `/opt/flutter` — the shared current stable SDK used as the default `flutter`
- `/opt/flutter-3.27.0` — the long-term supported Flutter 3.27 line for pinned repos
Shell helpers exposed in bench user environments:
- `flutter` / `dart` → current stable
- `flutter327` / `dart327` → pinned Flutter 3.27.0
Use project-local FVM where the repo pins a version. The baked 3.27 SDK exists to avoid slow first-run downloads for long-lived pinned projects.
## 🎯 Purpose
FlutterBench provides two ways to create Flutter projects with DevContainer support:
1. **🤖 Automated Setup** - Use `new-flutter-project.sh` for quick, standardized project creation
2. **🔧 Manual Setup** - Copy templates manually for maximum customization control
## 📁 Structure
```
flutterBench/
├── scripts/
│ ├── new-flutter-project.sh # Automated project creation
│ ├── new-dartwing-project.sh # DartWing project creation
│ ├── update-flutter-project.sh # Update existing projects
│ ├── launch-devbench.sh # Launch development container
│ └── start-monster.sh # Container startup script
├── templates/
│ └── flutter-devcontainer-template/ # DevContainer template
│ ├── .devcontainer/ # VS Code DevContainer config
│ ├── .vscode/ # VS Code settings & tasks
│ ├── scripts/
│ │ ├── manual-setup-project.sh # Manual setup validation
│ │ └── README.md # Script usage guide
│ ├── .env.example # Environment template
│ └── README.md # Template documentation
└── docs/ # Additional documentation
```
## 🚀 Getting Started
### Option 1: Automated Setup (Recommended)
**Best for**: New projects, standardized setup, quick start
```bash
# Navigate to flutterBench scripts
cd /path/to/workBenches/devBenches/flutterBench/scripts
# Create new Flutter project with DevContainer
./new-flutter-project.sh my-flutter-app
# Or specify custom target directory
./new-flutter-project.sh my-flutter-app ~/projects/special-projects
```
**What it does automatically:**
- ✅ Creates Flutter project using `flutter create`
- ✅ Copies and configures DevContainer template
- ✅ Sets up environment variables (`.env`)
- ✅ Configures user UID/GID for proper permissions
- ✅ Sets up infrastructure paths
- ✅ Includes specKit for spec-driven development
- ✅ Ready to open in VS Code
### Option 2: Manual Setup (Advanced)
**Best for**: Existing projects, template customization, learning/understanding
```bash
# 1. Create or navigate to your Flutter project
flutter create my-flutter-app # or use existing project
cd my-flutter-app
# 2. Copy template files
TEMPLATE_PATH="/path/to/workBenches/devBenches/flutterBench/templates/flutter-devcontainer-template"
cp -r "$TEMPLATE_PATH/.devcontainer" .
cp -r "$TEMPLATE_PATH/.vscode" .
cp -r "$TEMPLATE_PATH/scripts" .
cp "$TEMPLATE_PATH/.env.example" .
# 3. Set up environment configuration
cp .env.example .env
# Edit .env file with your project settings...
# 4. Validate setup (IMPORTANT!)
./scripts/manual-setup-project.sh
```
**When to use manual setup:**
- ✅ Adding DevContainer to existing Flutter project
- ✅ Need to customize template before applying
- ✅ Working with non-standard directory structure
- ✅ Want to understand how the template works
- ✅ Debugging container configuration issues
## 📋 Key Differences
| Feature | Automated Setup | Manual Setup |
|---------|----------------|-------------|
| **Speed** | ⚡ Fast (single command) | 🐢 Multiple steps required |
| **Control** | 🎯 Standardized | 🔧 Full customization |
| **Validation** | ✅ Built-in | 📋 Manual validation required |
| **Learning** | 📦 Black box | 🎓 Educational |
| **Best For** | New projects | Existing projects, customization |
| **Difficulty** | 🟢 Easy | 🟡 Intermediate |
## 🔧 Manual Setup Validation
**⚠️ IMPORTANT**: When using manual setup, you **MUST** run the validation script:
```bash
./scripts/manual-setup-project.sh
```
This script:
- 🔍 Creates `.env` from `.env.example` if missing
- ✅ Validates all required environment variables
- 🔧 Checks variable formats and values
- 🐳 Verifies Docker environment
- 📋 Tests container configuration
- 🏗️ Validates infrastructure paths
**📖 For detailed manual setup guidance**, see [`templates/flutter-devcontainer-template/scripts/README.md`](templates/flutter-devcontainer-template/scripts/README.md)
## 💡 Which Approach Should I Use?
### Use **Automated Setup** when:
- ✅ Creating a new Flutter project from scratch
- ✅ You want standard workBenches project structure
- ✅ You need to get started quickly
- ✅ You trust the default configuration
- ✅ You're new to DevContainers
### Use **Manual Setup** when:
- ✅ Adding DevContainer to existing Flutter project
- ✅ You need custom template modifications
- ✅ Working with unique directory structures
- ✅ You want to learn how DevContainers work
- ✅ Debugging container issues
- ✅ You need maximum control over the setup process
## ⚙️ Centralized Configuration Philosophy
**Key Principle: The `.env` file is the single source of truth for ALL project and user-specific configuration.**
### What This Means:
- ✅ **Template files remain untouched** - `devcontainer.json`, `docker-compose.yml`, etc. are never modified
- ✅ **All customization via environment variables** - container names, user settings, versions, ports
- ✅ **Project-specific settings isolated** - each project has its own `.env` file
- ✅ **Easy template updates** - template improvements don't conflict with your settings
### Configuration Examples:
```bash
# .env file controls everything:
PROJECT_NAME=dartwing
APP_CONTAINER_SUFFIX=app # Results in: dartwing-app
SERVICE_CONTAINER_SUFFIX=gateway # Results in: dartwing-gateway
USER_UID=1000
FLUTTER_VERSION=3.24.0
COMPOSE_PROJECT_NAME=dartwingers
```
**Result**: Template files use `${PROJECT_NAME}-${APP_CONTAINER_SUFFIX}` → resolves to `dartwing-app`
## 🚀 Next Steps After Setup
Regardless of which setup method you used:
1. **Open in VS Code**: `code .`
2. **Reopen in Container**: Click prompt or Ctrl+Shift+P → "Dev Containers: Reopen in Container"
3. **Wait for build**: First time takes 2-5 minutes
4. **Start coding**: Container includes Flutter SDK, Android tools, and VS Code extensions
## 🔧 Available Scripts
### Project Creation
- `scripts/new-flutter-project.sh` - Create new Flutter project with DevContainer
- `scripts/new-dartwing-project.sh` - Create new DartWing project variant
### Project Management
- `scripts/update-flutter-project.sh` - Update existing project to latest template
- `templates/.../scripts/manual-setup-project.sh` - Validate manual setup
### Development Environment
- `scripts/launch-devbench.sh` - Launch development container
- `scripts/start-monster.sh` - Ensure Layer 2 and Layer 3, then start the bench container
- `scripts/rebuild-stack.sh` - Check or rebuild the Flutter bench image stack
- `scripts/ensure-images.sh` - Lightweight Layer 2/Layer 3 check for devcontainer startup
### SonarCloud Coverage
- `sonarcloud-dart-flutter` - Run Dart/Flutter coverage and SonarCloud scan
`sonarcloud-dart-flutter` reads `SONARQUBE_TOKEN` from
`~/.config/sonarqube/sonar.env`. For Flutter projects it runs
`flutter test --coverage`; for pure Dart projects it runs the Dart `coverage`
package. Both paths produce `coverage/lcov.info`, then the helper invokes:
```bash
sonar-scanner -Dsonar.dart.lcov.reportPaths=coverage/lcov.info
```
Shell aliases: `flutter-sonar-coverage` and `dart-sonar-coverage`.
## 📚 Documentation
- [`templates/flutter-devcontainer-template/README.md`](templates/flutter-devcontainer-template/README.md) - Template details
- [`templates/flutter-devcontainer-template/scripts/README.md`](templates/flutter-devcontainer-template/scripts/README.md) - Manual setup guide
- [`docs/env-file-docker-compose-guide.md`](docs/env-file-docker-compose-guide.md) - Environment configuration guide
## 🎯 Template Features
The DevContainer template includes:
- 🐳 **Lightweight container** (~500MB vs 2GB+ FlutterBench)
- 🔧 **Centralized configuration** - ALL project and user settings in `.env` file only
- 📝 **No template file modification** - template files remain untouched, use environment variables
- 🏷️ **Configurable container naming** - customize app and service container names via `.env`
- 📱 **Shared ADB infrastructure** (connects to external ADB server)
- ⚙️ **VS Code integration** (tasks, launch configs, extensions)
- 🏗️ **Proper user permissions** (UID/GID matching)
- 🔄 **Hot reload support** (port forwarding configured)
- 🧪 **Testing support** (launch configurations)
- 📋 **Spec-driven development** (includes specKit)
## 🏗️ Container Philosophy
- **FlutterBench** = Heavy development workbench (~2GB, all tools)
- **Project Containers** = Lightweight project-specific environment (~500MB)
Use FlutterBench for heavy development, project containers for debugging and light development.