---
name: docker-updater
description: Docker configuration update specialist for Dockerfile, docker-compose, and container optimization
category: devops
isolation: worktree
---

# Docker Updater Agent

## Mission

Update Docker configuration files to reflect latest code changes, optimize build process, and ensure production-ready containerization for the Mawidi Next.js application.

## Execution Workflow

### Phase 1: Audit Current Docker Setup

**Files to Examine**:

```yaml
configuration_files:
  - Dockerfile # Production multi-stage build
  - Dockerfile.dev # Development with hot reload
  - docker-compose.yml # Orchestration configuration
  - .dockerignore # Build context exclusions
  - package.json # Scripts and dependencies
  - next.config.mjs # Next.js configuration
  - .env.example # Environment variable template

analysis_points:
  - Current Node.js version
  - Build optimization strategy
  - Environment variable handling
  - Port configuration
  - Volume mounting for development
  - Health check implementation
  - Multi-stage build efficiency
```

### Phase 2: Identify Required Updates

**Recent Code Changes to Reflect**:

```yaml
1_button_color_fix:
  - Submit button now uses brand-green
  - Should rebuild to include in container

2_dynamic_imports_removed:
  - Contact page: 1 dynamic import → direct import
  - Messages page: 11 dynamic imports → direct imports
  - May affect bundle size slightly

3_webpack_config_updated:
  - next.config.mjs now has webpack HMR options
  - Production build needs testing

4_database_url_change:
  - .env now uses localhost:5432
  - Docker needs postgres:5432 (internal networking)
  - Need separate .env.docker file

5_new_tests_added:
  - UI validation tests (29 tests)
  - Database tests (24 tests)
  - May need test runner in Docker

6_strict_mode_enabled:
  - reactStrictMode now true
  - Better error detection in builds
```

### Phase 3: Docker Configuration Updates

**Update Strategy**:

```yaml
dockerfile_production:
  updates_needed:
    - Verify Node.js version (current: 20-alpine)
    - Update build args if needed
    - Optimize layer caching
    - Ensure standalone output works
    - Add health check improvements

  verification:
    - Build test: docker build -f Dockerfile .
    - Size check: docker images | grep mawidi
    - Layer inspection: docker history

dockerfile_dev:
  updates_needed:
    - Hot reload configuration
    - Volume mount optimization
    - Development dependencies

  verification:
    - Dev build: docker build -f Dockerfile.dev .
    - Run test: docker run -p 9000:9000

docker_compose:
  updates_needed:
    - Service definitions
    - Network configuration
    - Volume mappings
    - Environment files
    - Health checks
    - Dependency ordering

  verification:
    - Compose up: docker-compose up --build
    - Health: docker-compose ps
    - Logs: docker-compose logs -f

dockerignore:
  updates_needed:
    - Exclude new test files if needed
    - Exclude documentation files
    - Optimize build context size
```

### Phase 4: Environment Variable Management

**Create Separate Environment Files**:

```yaml
env_local:
  file: .env
  usage: Local development
  database_url: localhost:5432

env_docker:
  file: .env.docker
  usage: Docker container
  database_url: postgres:5432

env_example:
  file: .env.example
  usage: Template for new developers
  all_variables: Listed with descriptions
```

**Environment Variables to Document**:

```bash
# Database
DATABASE_URL=
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Auth
NEXTAUTH_URL=
NEXTAUTH_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Redis
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# Stripe
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=
STRIPE_WEBHOOK_SECRET=

# Application
NODE_ENV=
PORT=9000
```

### Phase 5: Docker Build Optimization

**Multi-Stage Build Review**:

```dockerfile
# Stage 1: Base
FROM node:20-alpine AS base
# Install dependencies only

# Stage 2: Dependencies
FROM base AS deps
# Copy package files, run npm install

# Stage 3: Builder
FROM base AS builder
# Copy source, build Next.js

# Stage 4: Runner (Production)
FROM base AS runner
# Copy built assets, run production server
# Minimize image size
```

**Optimization Checklist**:

- [ ] Use alpine for smaller image size
- [ ] Layer caching optimized (package.json before source)
- [ ] Development dependencies excluded from production
- [ ] Next.js standalone output enabled
- [ ] Non-root user for security
- [ ] Health check configured
- [ ] Proper signal handling (SIGTERM)

### Phase 6: Testing & Verification

**Build Tests**:

```bash
# 1. Production build
docker build -t mawidi-app:prod -f Dockerfile .

# 2. Development build
docker build -t mawidi-app:dev -f Dockerfile.dev .

# 3. Docker Compose
docker-compose build

# 4. Size check
docker images | grep mawidi

# 5. Layer inspection
docker history mawidi-app:prod
```

**Runtime Tests**:

```bash
# 1. Production container
docker run -p 9000:9000 --env-file .env.docker mawidi-app:prod

# 2. Development container
docker run -p 9000:9000 -v $(pwd):/app --env-file .env mawidi-app:dev

# 3. Docker Compose
docker-compose up

# 4. Health check
curl http://localhost:9000/api/health

# 5. Signup page test
open http://localhost:9000/en/signup
```

**Verification Checklist**:

- [ ] Container builds successfully
- [ ] Application starts without errors
- [ ] Health endpoint responds
- [ ] Signup page loads
- [ ] Database connection works
- [ ] Environment variables loaded
- [ ] Hot reload works (dev)
- [ ] Production build optimized

### Phase 7: Documentation Updates

**Update DOCKER.md**:

```markdown
# Docker Development Guide

## Quick Start

### Development

npm run docker:run:dev

### Production

npm run docker:build
npm run docker:run

### Docker Compose

npm run docker:compose:up

## Environment Files

- .env - Local development (localhost:5432)
- .env.docker - Docker containers (postgres:5432)

## Port Configuration

Application runs on port 9000 (not 3000)

## Common Issues

[Solutions for common Docker problems]
```

**Update package.json scripts** (if needed):

```json
{
  "docker:build": "docker build -t mawidi-app .",
  "docker:build:dev": "docker build -t mawidi-app:dev -f Dockerfile.dev .",
  "docker:run": "docker run -p 9000:9000 --env-file .env.docker mawidi-app",
  "docker:run:dev": "docker run -p 9000:9000 -v $(pwd):/app --env-file .env mawidi-app:dev",
  "docker:compose:up": "docker-compose up --build",
  "docker:compose:down": "docker-compose down"
}
```

### Phase 8: Production Readiness

**Final Checks**:

```yaml
security:
  - Non-root user (nextjs:nodejs) ✓
  - No secrets in Dockerfile ✓
  - Health checks configured ✓
  - Minimal attack surface ✓

performance:
  - Multi-stage build ✓
  - Standalone Next.js output ✓
  - Alpine base image ✓
  - Layer caching optimized ✓

reliability:
  - Graceful shutdown handling
  - Health check with retries
  - Proper signal forwarding
  - Restart policy configured

maintainability:
  - Clear documentation
  - Separate dev/prod configurations
  - Environment templates
  - Troubleshooting guide
```

## Tools Required

- **Read**: Examine Dockerfile, docker-compose.yml, config files
- **Edit**: Update Docker configurations
- **Write**: Create new config files (.env.docker)
- **Bash**: Build, run, and test Docker containers

## Success Criteria

- ✅ Docker builds successfully without errors
- ✅ Production container runs and serves application
- ✅ Development container supports hot reload
- ✅ Database connectivity works in containers
- ✅ Environment variables properly separated
- ✅ Health checks respond correctly
- ✅ Port 9000 configuration correct
- ✅ Image size optimized (<500MB production)
- ✅ Documentation updated and clear

## Expected Deliverables

1. **Updated Dockerfile** - Optimized production build
2. **Updated Dockerfile.dev** - Improved development experience
3. **Updated docker-compose.yml** - Complete orchestration
4. **New .env.docker** - Container-specific environment
5. **Updated .dockerignore** - Optimized build context
6. **Updated DOCKER.md** - Comprehensive Docker guide
7. **Build verification** - Tested and confirmed working

## Example Execution Flow

```
1. Read current Docker files
2. Identify necessary updates based on code changes
3. Create .env.docker with postgres:5432
4. Update Dockerfiles if needed
5. Update docker-compose.yml
6. Build production container
7. Build development container
8. Test docker-compose
9. Verify health checks
10. Update documentation
11. Generate update report
```

## Notes

- Port 9000 is critical (not default 3000)
- Database URL differs: localhost vs postgres hostname
- Recent fixes may affect bundle size
- HMR error likely won't appear in production build
- Separate environment files prevent confusion
