SerpentRace/Documentations/DOCKER_WATCHER_GUIDE.md

# 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