legal-doc-masker/DOCKER_MIGRATION_GUIDE.md

Docker Image Migration Guide

This guide explains how to export your built Docker images, transfer them to another environment, and run them without rebuilding.

Overview

The migration process involves:

1. Export: Save built images to tar files
2. Transfer: Copy tar files to target environment
3. Import: Load images on target environment
4. Run: Start services with imported images

Prerequisites

Source Environment (where images are built)

• Docker installed and running
• All services built and working
• Sufficient disk space for image export

Target Environment (where images will run)

• Docker installed and running
• Sufficient disk space for image import
• Network access to source environment (or USB drive)

Step 1: Export Docker Images

1.1 List Current Images

First, check what images you have:

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}"

You should see images like:

• legal-doc-masker-backend-api
• legal-doc-masker-frontend
• legal-doc-masker-mineru-api
• redis:alpine

1.2 Export Individual Images

Create a directory for exports:

mkdir -p docker-images-export
cd docker-images-export

Export each image:

# Export backend image
docker save legal-doc-masker-backend-api:latest -o backend-api.tar

# Export frontend image
docker save legal-doc-masker-frontend:latest -o frontend.tar

# Export mineru image
docker save legal-doc-masker-mineru-api:latest -o mineru-api.tar

# Export redis image (if not using official)
docker save redis:alpine -o redis.tar

1.3 Export All Images at Once (Alternative)

If you want to export all images in one command:

# Export all project images
docker save \
  legal-doc-masker-backend-api:latest \
  legal-doc-masker-frontend:latest \
  legal-doc-masker-mineru-api:latest \
  redis:alpine \
  -o legal-doc-masker-all.tar

1.4 Verify Export Files

Check the exported files:

ls -lh *.tar

You should see files like:

• backend-api.tar (~200-500MB)
• frontend.tar (~100-300MB)
• mineru-api.tar (~1-3GB)
• redis.tar (~30-50MB)

Step 2: Transfer Images

2.1 Transfer via Network (SCP/RSYNC)

# Transfer to remote server
scp *.tar user@remote-server:/path/to/destination/

# Or using rsync (more efficient for large files)
rsync -avz --progress *.tar user@remote-server:/path/to/destination/

2.2 Transfer via USB Drive

# Copy to USB drive
cp *.tar /Volumes/USB_DRIVE/docker-images/

# Or create a compressed archive
tar -czf legal-doc-masker-images.tar.gz *.tar
cp legal-doc-masker-images.tar.gz /Volumes/USB_DRIVE/

2.3 Transfer via Cloud Storage

# Upload to cloud storage (example with AWS S3)
aws s3 cp *.tar s3://your-bucket/docker-images/

# Or using Google Cloud Storage
gsutil cp *.tar gs://your-bucket/docker-images/

Step 3: Import Images on Target Environment

3.1 Prepare Target Environment

# Create directory for images
mkdir -p docker-images-import
cd docker-images-import

# Copy images from transfer method
# (SCP, USB, or download from cloud storage)

3.2 Import Individual Images

# Import backend image
docker load -i backend-api.tar

# Import frontend image
docker load -i frontend.tar

# Import mineru image
docker load -i mineru-api.tar

# Import redis image
docker load -i redis.tar

3.3 Import All Images at Once (if exported together)

docker load -i legal-doc-masker-all.tar

3.4 Verify Imported Images

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}"

Step 4: Prepare Target Environment

4.1 Copy Project Files

Transfer the following files to target environment:

# Essential files to copy
docker-compose.yml
DOCKER_COMPOSE_README.md
setup-unified-docker.sh

# Environment files (if they exist)
backend/.env
frontend/.env
mineru/.env

# Storage directories (if you want to preserve data)
backend/storage/
mineru/storage/
backend/legal_doc_masker.db

4.2 Create Directory Structure

# Create necessary directories
mkdir -p backend/storage
mkdir -p mineru/storage/uploads
mkdir -p mineru/storage/processed

Step 5: Run Services

5.1 Start All Services

# Start all services using imported images
docker-compose up -d

5.2 Verify Services

# Check service status
docker-compose ps

# Check service logs
docker-compose logs -f

5.3 Test Endpoints

# Test frontend
curl -I http://localhost:3000

# Test backend API
curl -I http://localhost:8000/api/v1

# Test mineru API
curl -I http://localhost:8001/health

Automation Scripts

Export Script

Create export-images.sh:

#!/bin/bash

set -e

echo "🚀 Exporting Docker Images"

# Create export directory
mkdir -p docker-images-export
cd docker-images-export

# Export images
echo "📦 Exporting backend-api image..."
docker save legal-doc-masker-backend-api:latest -o backend-api.tar

echo "📦 Exporting frontend image..."
docker save legal-doc-masker-frontend:latest -o frontend.tar

echo "📦 Exporting mineru-api image..."
docker save legal-doc-masker-mineru-api:latest -o mineru-api.tar

echo "📦 Exporting redis image..."
docker save redis:alpine -o redis.tar

# Show file sizes
echo "📊 Export complete. File sizes:"
ls -lh *.tar

echo "✅ Images exported successfully!"

Import Script

Create import-images.sh:

#!/bin/bash

set -e

echo "🚀 Importing Docker Images"

# Check if tar files exist
if [ ! -f "backend-api.tar" ]; then
    echo "❌ backend-api.tar not found"
    exit 1
fi

# Import images
echo "📦 Importing backend-api image..."
docker load -i backend-api.tar

echo "📦 Importing frontend image..."
docker load -i frontend.tar

echo "📦 Importing mineru-api image..."
docker load -i mineru-api.tar

echo "📦 Importing redis image..."
docker load -i redis.tar

# Verify imports
echo "📊 Imported images:"
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep legal-doc-masker

echo "✅ Images imported successfully!"

Troubleshooting

Common Issues

1. Image not found during import

   # Check if image exists
   docker images | grep image-name
   
   # Re-export if needed
   docker save image-name:tag -o image-name.tar
   

2. Port conflicts on target environment

   # Check what's using the ports
   lsof -i :8000
   lsof -i :8001
   lsof -i :3000
   
   # Modify docker-compose.yml if needed
   ports:
     - "8002:8000"  # Change external port
   

3. Permission issues

   # Fix file permissions
   chmod +x setup-unified-docker.sh
   chmod +x export-images.sh
   chmod +x import-images.sh
   

4. Storage directory issues

   # Create directories with proper permissions
   sudo mkdir -p backend/storage
   sudo mkdir -p mineru/storage/uploads
   sudo mkdir -p mineru/storage/processed
   sudo chown -R $USER:$USER backend/storage mineru/storage
   

Performance Optimization

1. Compress images for transfer

   # Compress before transfer
   gzip *.tar
   
   # Decompress on target
   gunzip *.tar.gz
   

2. Use parallel transfer

   # Transfer multiple files in parallel
   parallel scp {} user@server:/path/ ::: *.tar
   

3. Use Docker registry (alternative)

   # Push to registry
   docker tag legal-doc-masker-backend-api:latest your-registry/backend-api:latest
   docker push your-registry/backend-api:latest
   
   # Pull on target
   docker pull your-registry/backend-api:latest
   

Complete Migration Checklist

• Export all Docker images
• Transfer image files to target environment
• Transfer project configuration files
• Import images on target environment
• Create necessary directories
• Start services
• Verify all services are running
• Test all endpoints
• Update any environment-specific configurations

Security Considerations

1. Secure transfer: Use encrypted transfer methods (SCP, SFTP)
2. Image verification: Verify image integrity after transfer
3. Environment isolation: Ensure target environment is properly secured
4. Access control: Limit access to Docker daemon on target environment

Cost Optimization

1. Image size: Remove unnecessary layers before export
2. Compression: Use compression for large images
3. Selective transfer: Only transfer images you need
4. Cleanup: Remove old images after successful migration