motovaultpro/docs/redesign/PHASE-01-DOCKER-COMPOSE.md

Phase 1: Docker Compose Simplification

Agent Assignment

Primary Agent: infra-agent Collaborators: None Estimated Duration: 25-30 minutes

Prerequisites

• Phases that must complete first: Phase 4 (Config Cleanup)
• Files that must not be locked: docker-compose.yml
• System state: All containers stopped or ready for restart

Objectives

1. Rename all services from admin-* to mvp-* naming convention
2. Rename mvp-platform-vehicles-api to mvp-platform
3. Remove 8 unnecessary platform service containers
4. Add filesystem volume mount for document storage
5. Update all Traefik labels for new service names
6. Ensure 6 containers total in final configuration

Files to Modify

docker-compose.yml

Action: Major restructure Location: /docker-compose.yml

Step-by-Step Instructions

Step 1: Stop All Running Containers

# Stop all services
docker compose down

# Verify all stopped
docker compose ps
# Expected: No containers listed

Step 2: Backup Current docker-compose.yml

# Create backup
cp docker-compose.yml docker-compose.yml.backup-phase1-$(date +%Y%m%d)

# Verify backup
ls -la docker-compose.yml*

Step 3: Rename Services

Services to Rename:

# OLD → NEW
traefik → mvp-traefik
admin-frontend → mvp-frontend
admin-backend → mvp-backend
admin-postgres → mvp-postgres
admin-redis → mvp-redis
mvp-platform-vehicles-api → mvp-platform

Find and Replace:

# In docker-compose.yml, replace:
sed -i.bak 's/admin-frontend/mvp-frontend/g' docker-compose.yml
sed -i.bak 's/admin-backend/mvp-backend/g' docker-compose.yml
sed -i.bak 's/admin-postgres/mvp-postgres/g' docker-compose.yml
sed -i.bak 's/admin-redis/mvp-redis/g' docker-compose.yml
sed -i.bak 's/mvp-platform-vehicles-api/mvp-platform/g' docker-compose.yml

# Note: traefik already has correct name

Step 4: Remove Platform Services

Delete these entire service definitions from docker-compose.yml:

admin-minio:              # DELETE entire block
mvp-platform-landing:     # DELETE entire block
mvp-platform-tenants:     # DELETE entire block
platform-postgres:        # DELETE entire block
platform-redis:           # DELETE entire block
mvp-platform-vehicles-db: # DELETE entire block
mvp-platform-vehicles-redis: # DELETE entire block
mvp-platform-vehicles-etl:   # DELETE entire block

Step 5: Add Filesystem Volume Mount

Add to mvp-backend service:

mvp-backend:
  # ... existing config ...
  volumes:
    - ./config/app/production.yml:/app/config/production.yml:ro
    - ./secrets/app/postgres-password.txt:/run/secrets/postgres-password:ro
    - ./data/documents:/app/data/documents  # ADD THIS LINE
  # ... rest of config ...

Create directory on host:

mkdir -p ./data/documents
chmod 755 ./data/documents

Step 6: Update Volume Names

Find and replace volume names:

# OLD volumes:
admin_postgres_data
admin_redis_data
admin_minio_data  # DELETE

# NEW volumes:
mvp_postgres_data
mvp_redis_data

At bottom of docker-compose.yml:

volumes:
  mvp_postgres_data:
    name: mvp_postgres_data
  mvp_redis_data:
    name: mvp_redis_data
  # Remove admin_minio_data

Step 7: Update Traefik Labels

For mvp-frontend:

mvp-frontend:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.mvp-frontend.rule=Host(`admin.motovaultpro.com`)"  # Updated
    - "traefik.http.routers.mvp-frontend.entrypoints=websecure"
    - "traefik.http.routers.mvp-frontend.tls=true"
    - "traefik.http.services.mvp-frontend.loadbalancer.server.port=80"  # Updated service name

For mvp-backend:

mvp-backend:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.mvp-backend.rule=Host(`admin.motovaultpro.com`) && PathPrefix(`/api`)"
    - "traefik.http.routers.mvp-backend.entrypoints=websecure"
    - "traefik.http.routers.mvp-backend.tls=true"
    - "traefik.http.services.mvp-backend.loadbalancer.server.port=3001"  # Updated service name

For mvp-platform:

mvp-platform:
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.mvp-platform.rule=Host(`admin.motovaultpro.com`) && PathPrefix(`/platform`)"
    - "traefik.http.routers.mvp-platform.entrypoints=websecure"
    - "traefik.http.routers.mvp-platform.tls=true"
    - "traefik.http.services.mvp-platform.loadbalancer.server.port=8000"  # Updated service name

Step 8: Update Internal Service References

In mvp-backend environment variables or config:

mvp-backend:
  environment:
    - DATABASE_HOST=mvp-postgres  # Updated from admin-postgres
    - REDIS_HOST=mvp-redis        # Updated from admin-redis
    - PLATFORM_VEHICLES_API_URL=http://mvp-platform:8000  # Updated

In mvp-platform:

mvp-platform:
  environment:
    - DATABASE_HOST=mvp-postgres  # Will use same postgres as backend
    - REDIS_HOST=mvp-redis        # Will use same redis as backend

Step 9: Validate docker-compose.yml

# Validate syntax
docker compose config

# Expected: No errors, valid YAML output

# Check service count
docker compose config --services | wc -l
# Expected: 6

Step 10: Update .env if Needed

Ensure .env references new service names:

# .env should have:
DATABASE_URL=postgresql://postgres:password@mvp-postgres:5432/motovaultpro
REDIS_URL=redis://mvp-redis:6379
PLATFORM_VEHICLES_API_URL=http://mvp-platform:8000

Step 11: Start Services

# Build and start all containers
docker compose up -d --build

# Check status
docker compose ps
# Expected: 6 services running

# Expected services:
# - mvp-traefik
# - mvp-frontend
# - mvp-backend
# - mvp-postgres
# - mvp-redis
# - mvp-platform

Step 12: Verify Traefik Dashboard

# Access Traefik dashboard
open http://localhost:8080

# Check discovered services
curl -s http://localhost:8080/api/http/services | jq -r '.[].name'
# Expected to see: mvp-frontend, mvp-backend, mvp-platform

# Check routers
curl -s http://localhost:8080/api/http/routers | jq -r '.[].name'
# Expected to see: mvp-frontend, mvp-backend, mvp-platform routers

Validation Criteria

Container Validation

• Exactly 6 containers running
• All containers have "healthy" or "running" status
• No "admin-*" named containers (except in volumes)
• mvp-platform exists (not mvp-platform-vehicles-api)

Validation Command:

docker compose ps --format "table {{.Service}}\t{{.Status}}"

Service Validation

• mvp-traefik accessible at localhost:8080
• mvp-frontend accessible at https://admin.motovaultpro.com
• mvp-backend accessible at https://admin.motovaultpro.com/api/health
• mvp-postgres accepting connections
• mvp-redis accepting connections
• mvp-platform accessible (internal)

Validation Commands:

# Test Traefik
curl -s http://localhost:8080/api/version | jq

# Test backend health
curl -s -k https://admin.motovaultpro.com/api/health

# Test postgres
docker compose exec mvp-postgres pg_isready -U postgres

# Test redis
docker compose exec mvp-redis redis-cli ping
# Expected: PONG

# Test platform service (internal)
docker compose exec mvp-backend curl http://mvp-platform:8000/health

Volume Validation

• mvp_postgres_data volume exists
• mvp_redis_data volume exists
• ./data/documents directory exists and is writable
• No admin_minio_data volume

Validation Commands:

# Check volumes
docker volume ls | grep mvp
# Expected: mvp_postgres_data, mvp_redis_data

# Check filesystem mount
docker compose exec mvp-backend ls -la /app/data/documents
# Expected: Directory exists, writable

# Verify no MinIO volume
docker volume ls | grep minio
# Expected: Empty (no results)

Network Validation (Phase 5 will simplify further)

• Services can communicate internally
• Traefik can route to all services
• No network errors in logs

Validation Commands:

# Test internal communication
docker compose exec mvp-backend ping -c 1 mvp-postgres
docker compose exec mvp-backend ping -c 1 mvp-redis
docker compose exec mvp-backend ping -c 1 mvp-platform

# Check logs for network errors
docker compose logs mvp-backend | grep -i "network\|connection"
# Expected: No critical errors

Rollback Procedure

If validation fails:

# 1. Stop containers
docker compose down

# 2. Restore backup
cp docker-compose.yml.backup-phase1-YYYYMMDD docker-compose.yml

# 3. Restart with original config
docker compose up -d

# 4. Verify rollback
docker compose ps
# Expected: 14 containers (original state)

See ROLLBACK-STRATEGY.md Phase 1 section for detailed procedure.

Dependencies on Other Phases

Blocks These Phases:

• Phase 5 (Network Simplification) - needs new service names
• Phase 7 (Database Updates) - needs new container names
• Phase 8 (Platform Service) - needs new mvp-platform name

Blocked By:

• Phase 4 (Config Cleanup) - needs clean configuration first

Estimated Duration

25-30 minutes

• Backup and preparation: 5 minutes
• Service renaming: 10 minutes
• Validation: 10 minutes
• Troubleshooting buffer: 5 minutes

Conflict Zones

None - This phase exclusively owns docker-compose.yml during execution.

Success Indicators

1. docker compose config validates successfully
2. All 6 containers start and reach healthy status
3. Traefik dashboard shows 3 services
4. Application accessible via browser
5. No errors in container logs

Update EXECUTION-STATE.json

{
  "phases": {
    "1": {
      "status": "in_progress",
      "started_at": "[timestamp]",
      "agent": "infra-agent"
    }
  }
}

On completion:

{
  "phases": {
    "1": {
      "status": "completed",
      "started_at": "[timestamp]",
      "completed_at": "[timestamp]",
      "duration_minutes": 28,
      "validation_passed": true
    }
  }
}

Next Phase

After successful completion, infra-agent can proceed to Phase 5 (Network Simplification), and platform-agent can start Phase 8 (Platform Service Simplification).