rehearshalhub/DEVELOPMENT_TASKS_OPTIMIZATION.md

Development Tasks Optimization Summary

Overview

Comprehensive optimization of the development workflow to reduce Docker overhead, preserve network/proxy configuration, and streamline the development process.

Changes Made

1. Docker Configuration Fixes

File: docker-compose.dev.yml

• ✅ Changed target: production to target: development for both api and web services
• Impact: Enables hot reload and development-specific features

2. Streamlined Task Structure

File: Taskfile.yml

New Task Structure:

dev:up          # Main development task (recommended)
dev:build       # Explicit container building
dev:clean       # Safe cleanup (preserves network)
dev:nuke        # Full cleanup (when network corrupted)
dev:restart     # Quick service restart
dev:help        # Task documentation

Removed Redundant Tasks:

• dev:full → Replaced with dev:up
• dev:audio-debug → Use dev:up with debug env vars
• Conflicting frontend server management

3. Optimized Development Tasks

dev:up - Main Development Task

dev:up:
  desc: Start complete development server (recommended)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} up -d {{.DEV_SERVICES}}"
    - "{{.COMPOSE}} {{.DEV_FLAGS}} logs -f api web audio-worker nc-watcher"

• Benefits: Single command to start everything, follows logs
• Usage: task dev:up

dev:build - Smart Building

dev:build:
  desc: Build development containers (only when dependencies change)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} build --pull api web"

• Benefits: Explicit build step, uses --pull for latest base images
• Usage: task dev:build (run when dependencies change)

dev:clean - Safe Cleanup

dev:clean:
  desc: Safe cleanup (preserves network/proxy, removes containers/volumes)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} down"
    - docker volume rm -f $(docker volume ls -q | grep rehearsalhub) || true

• Benefits: Preserves network/proxy configuration
• Usage: task dev:clean

dev:nuke - Full Cleanup

dev:nuke:
  desc: Full cleanup (removes everything including network - use when network is corrupted)
  cmds:
    - "{{.COMPOSE}} {{.DEV_FLAGS}} down -v"
    - docker system prune -f --volumes

• Benefits: Complete cleanup when network issues occur
• Usage: task dev:nuke (rarely needed)

4. Audio Service Enhancements

File: web/src/services/audioService.ts

• ✅ Added development mode detection with automatic debug logging
• ✅ Development-specific WaveSurfer configuration
• ✅ Better audio context management

Workflow Recommendations

Daily Development

# Start development (first time or after clean)
task dev:up

# Make code changes (hot reload works automatically)
# ... edit files ...

# When done
task dev:clean

When Dependencies Change

# Rebuild containers
task dev:build
task dev:up

When Network Issues Occur

# Full cleanup and restart
task dev:nuke
task dev:up

Benefits Achieved

✅ Reduced Docker Overhead

• Smart Building: Only rebuild when necessary
• Layer Caching: Docker uses built-in layer caching
• Minimal Downloads: --pull only updates base images when needed

✅ Reliable Networking

• Network Preservation: dev:clean preserves proxy network
• Safe Cleanup: No accidental network destruction
• Explicit Control: dev:nuke for when network is truly corrupted

✅ Simpler Workflow

• Clear Recommendations: dev:up is the main task
• Logical Separation: Build vs run vs cleanup
• Better Documentation: task help shows all options

✅ Better Development Experience

• Hot Reload: Development targets enable live reloading
• Debugging: Automatic debug mode detection
• Quick Restarts: dev:restart for fast iteration

Performance Comparison

Before Optimization

• ❌ Frequent full rebuilds
• ❌ Network destruction on cleanup
• ❌ Confusing task structure
• ❌ Production targets in development
• ❌ No clear workflow recommendations

After Optimization

• ✅ Smart incremental builds
• ✅ Network preservation
• ✅ Streamlined task structure
• ✅ Proper development targets
• ✅ Clear workflow documentation

Migration Guide

For Existing Developers

1. Clean up old environment:

   task dev:nuke  # Only if you have network issues
   

2. Start fresh:

   task dev:up
   

3. Update your workflow:

   • Use dev:up instead of dev:full
   • Use dev:build when you change dependencies
   • Use dev:clean for normal cleanup

For New Developers

1. Start development:

   task dev:up
   

2. See available tasks:

   task help
   

3. Clean up when done:

   task dev:clean
   

Troubleshooting

Audio Playback Issues

• Ensure you're using dev:up (development targets)
• Check browser console for WebAudio errors
• Use task dev:build if you've changed audio dependencies

Network/Proxy Issues

• Try dev:clean first (preserves network)
• If still broken, use dev:nuke (full cleanup)
• Check that proxy network exists: docker network ls | grep proxy

Build Issues

• Run dev:build explicitly when dependencies change
• Check Docker layer caching with docker system df
• Use --no-cache if needed: docker compose build --no-cache

Future Enhancements

Potential Improvements

1. Automatic Rebuild Detection: Watch dependency files and auto-rebuild
2. Cache Mounts: Use Docker build cache mounts for even faster builds
3. Multi-stage Optimization: Further optimize Dockerfile layer ordering
4. Task Aliases: Add shortcuts like task up → task dev:up
5. Environment Validation: Auto-check for required tools and configs