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

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

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)

# Start with file watchers
.\docker-manage.bat dev:watch

# Traditional start (without watchers)
.\docker-manage.bat dev:start

Linux/Mac (docker-manage.sh)

# 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

# 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