docs: add comprehensive documentation for optimized development tasks
This commit is contained in:
Mistral Vibe
206
DEVELOPMENT_TASKS_OPTIMIZATION.md
Normal file
206
DEVELOPMENT_TASKS_OPTIMIZATION.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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:
|
||||
```bash
|
||||
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
|
||||
```yaml
|
||||
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
|
||||
```yaml
|
||||
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
|
||||
```yaml
|
||||
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
|
||||
```yaml
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Rebuild containers
|
||||
task dev:build
|
||||
task dev:up
|
||||
```
|
||||
|
||||
### When Network Issues Occur
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
task dev:nuke # Only if you have network issues
|
||||
```
|
||||
|
||||
2. **Start fresh**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
task dev:up
|
||||
```
|
||||
|
||||
2. **See available tasks**:
|
||||
```bash
|
||||
task help
|
||||
```
|
||||
|
||||
3. **Clean up when done**:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user