236 lines
7.0 KiB
Markdown
236 lines
7.0 KiB
Markdown
# Docker Watcher Implementation Guide
|
|
|
|
## Overview
|
|
|
|
This document explains the Docker watcher implementation for the SerpentRace project, which automatically synchronizes local file changes with Docker containers and rebuilds images when necessary.
|
|
|
|
## What's Implemented
|
|
|
|
### Docker Compose Watch Configuration
|
|
|
|
The development Docker Compose configuration now includes `develop.watch` sections for both frontend and backend services that provide:
|
|
|
|
1. **File Synchronization**: Automatically sync source code changes to running containers
|
|
2. **Selective Rebuilding**: Rebuild containers when critical configuration files change
|
|
3. **Intelligent Ignore Patterns**: Exclude unnecessary files like `node_modules`
|
|
|
|
### Backend Watcher Configuration
|
|
|
|
```yaml
|
|
develop:
|
|
watch:
|
|
- action: sync
|
|
path: ../SerpentRace_Backend/src
|
|
target: /app/src
|
|
ignore:
|
|
- node_modules/
|
|
- action: sync
|
|
path: ../SerpentRace_Backend/package.json
|
|
target: /app/package.json
|
|
- action: rebuild
|
|
path: ../SerpentRace_Backend/package-lock.json
|
|
- action: rebuild
|
|
path: ../SerpentRace_Docker/Dockerfile_backend.dev
|
|
```
|
|
|
|
### Frontend Watcher Configuration
|
|
|
|
```yaml
|
|
develop:
|
|
watch:
|
|
- action: sync
|
|
path: ../SerpentRace_Frontend/src
|
|
target: /app/src
|
|
ignore:
|
|
- node_modules/
|
|
- action: sync
|
|
path: ../SerpentRace_Frontend/public
|
|
target: /app/public
|
|
- action: sync
|
|
path: ../SerpentRace_Frontend/package.json
|
|
target: /app/package.json
|
|
- action: rebuild
|
|
path: ../SerpentRace_Frontend/package-lock.json
|
|
- action: rebuild
|
|
path: ../SerpentRace_Frontend/vite.config.js
|
|
- action: rebuild
|
|
path: ../SerpentRace_Docker/Dockerfile_frontend.dev
|
|
```
|
|
|
|
## How It Works
|
|
|
|
### Sync Actions
|
|
- **Purpose**: Instantly copy changed files from host to container
|
|
- **Use Cases**: Source code files, static assets, configuration files that don't require rebuild
|
|
- **Performance**: Near-instant updates, no container restart needed
|
|
|
|
### Rebuild Actions
|
|
- **Purpose**: Trigger full container rebuild when critical files change
|
|
- **Use Cases**: Package files, Docker configuration, build configuration
|
|
- **Performance**: Takes longer but ensures consistency
|
|
|
|
## Usage
|
|
|
|
### New Commands Added
|
|
|
|
#### Windows (docker-manage.bat)
|
|
```bash
|
|
# Start with file watchers
|
|
.\docker-manage.bat dev:watch
|
|
|
|
# Traditional start (without watchers)
|
|
.\docker-manage.bat dev:start
|
|
```
|
|
|
|
#### Linux/Mac (docker-manage.sh)
|
|
```bash
|
|
# Start with file watchers
|
|
./docker-manage.sh dev:watch
|
|
|
|
# Traditional start (without watchers)
|
|
./docker-manage.sh dev:start
|
|
```
|
|
|
|
### Command Differences
|
|
|
|
| Command | Mode | File Watching | Container Rebuild | Use Case |
|
|
|---------|------|---------------|-------------------|----------|
|
|
| `dev:start` | Background (-d) | No | Manual only | Traditional development |
|
|
| `dev:watch` | Foreground | Yes | Automatic | Modern development with live sync |
|
|
|
|
## Benefits
|
|
|
|
### 1. Instant File Synchronization
|
|
- Source code changes are immediately available in containers
|
|
- No manual rebuild or restart required for code changes
|
|
- Maintains all existing hot-reload functionality (nodemon, Vite HMR)
|
|
|
|
### 2. Smart Rebuilding
|
|
- Automatically rebuilds when package.json or Dockerfile changes
|
|
- Ensures containers stay consistent with dependency updates
|
|
- Prevents common issues with stale dependencies
|
|
|
|
### 3. Development Efficiency
|
|
- Combines Docker's isolation with native-like development speed
|
|
- Reduces context switching between local and containerized development
|
|
- Maintains consistent environment across team members
|
|
|
|
## File Patterns Watched
|
|
|
|
### Backend
|
|
- **Synced Files**:
|
|
- `src/` directory (all TypeScript source files)
|
|
- `package.json` (for runtime reference)
|
|
- **Rebuild Triggers**:
|
|
- `package-lock.json` (dependency changes)
|
|
- `Dockerfile_backend.dev` (container configuration)
|
|
|
|
### Frontend
|
|
- **Synced Files**:
|
|
- `src/` directory (React components, styles, etc.)
|
|
- `public/` directory (static assets)
|
|
- `package.json` (for runtime reference)
|
|
- **Rebuild Triggers**:
|
|
- `package-lock.json` (dependency changes)
|
|
- `vite.config.js` (build configuration)
|
|
- `Dockerfile_frontend.dev` (container configuration)
|
|
|
|
## Performance Considerations
|
|
|
|
### Sync Performance
|
|
- File synchronization is near-instantaneous
|
|
- Uses Docker's built-in file watching mechanisms
|
|
- Optimized for development workloads
|
|
|
|
### Rebuild Performance
|
|
- Rebuilds only occur when necessary
|
|
- Docker layer caching reduces rebuild times
|
|
- Can be resource-intensive for large dependency changes
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **File Changes Not Reflected**
|
|
- Ensure you're using `dev:watch` command
|
|
- Check that files are not in ignore patterns
|
|
- Verify file paths are correct
|
|
|
|
2. **Excessive Rebuilds**
|
|
- Check for unnecessary changes to rebuild trigger files
|
|
- Consider moving files to sync-only patterns if appropriate
|
|
|
|
3. **Performance Issues**
|
|
- Monitor Docker resource usage
|
|
- Consider excluding large directories from watching
|
|
- Use `.dockerignore` for files that should never be synced
|
|
|
|
### Debugging Commands
|
|
|
|
```bash
|
|
# Check container status
|
|
docker-compose -f SerpentRace_Docker/docker-compose.dev.yml ps
|
|
|
|
# View watcher logs
|
|
docker-compose -f SerpentRace_Docker/docker-compose.dev.yml logs -f backend
|
|
docker-compose -f SerpentRace_Docker/docker-compose.dev.yml logs -f frontend
|
|
|
|
# Check file synchronization
|
|
docker exec -it serpentrace-backend-dev ls -la /app/src
|
|
docker exec -it serpentrace-frontend-dev ls -la /app/src
|
|
```
|
|
|
|
## Requirements
|
|
|
|
### Docker Compose Version
|
|
- Requires Docker Compose v2.22+ for `develop.watch` support
|
|
- Check version: `docker-compose version`
|
|
|
|
### File System
|
|
- Works on Windows, Linux, and macOS
|
|
- Performance may vary based on file system type
|
|
- WSL2 recommended for Windows users
|
|
|
|
## Migration from Traditional Setup
|
|
|
|
### No Breaking Changes
|
|
- Existing `dev:start` command continues to work
|
|
- All volume mounts remain functional
|
|
- Hot reload functionality preserved
|
|
|
|
### Gradual Adoption
|
|
1. Try `dev:watch` for active development
|
|
2. Use `dev:start` for background services
|
|
3. Gradually migrate team to new workflow
|
|
|
|
## Best Practices
|
|
|
|
### Development Workflow
|
|
1. Use `dev:watch` during active development
|
|
2. Make code changes normally
|
|
3. Watch for automatic synchronization
|
|
4. Monitor logs for any sync issues
|
|
|
|
### File Organization
|
|
- Keep frequently changed files in sync patterns
|
|
- Place build configuration in rebuild patterns
|
|
- Use `.dockerignore` for files that should never sync
|
|
|
|
### Team Collaboration
|
|
- Document which command team members should use
|
|
- Ensure consistent Docker Compose version across team
|
|
- Share troubleshooting steps for common issues
|
|
|
|
## Future Enhancements
|
|
|
|
### Potential Improvements
|
|
1. **Selective Service Watching**: Watch only specific services
|
|
2. **Custom Ignore Patterns**: Per-developer ignore configurations
|
|
3. **Performance Monitoring**: Built-in sync performance metrics
|
|
4. **Integration with IDEs**: Better editor integration for sync status
|
|
|
|
### Configuration Expansion
|
|
- Additional file patterns as needed
|
|
- Service-specific watch configurations
|
|
- Environment-based watch rules
|