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:

```bash
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:

```bash
mkdir -p docker-images-export
cd docker-images-export
```

Export each image:

```bash
# 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:

```bash
# 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:

```bash
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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

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

### 3.4 Verify Imported Images

```bash
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:

```bash
# 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

```bash
# 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

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

### 5.2 Verify Services

```bash
# Check service status
docker-compose ps

# Check service logs
docker-compose logs -f
```

### 5.3 Test Endpoints

```bash
# 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`:

```bash
#!/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`:

```bash
#!/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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # Fix file permissions
   chmod +x setup-unified-docker.sh
   chmod +x export-images.sh
   chmod +x import-images.sh
   ```

4. **Storage directory issues**
   ```bash
   # 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**
   ```bash
   # Compress before transfer
   gzip *.tar
   
   # Decompress on target
   gunzip *.tar.gz
   ```

2. **Use parallel transfer**
   ```bash
   # Transfer multiple files in parallel
   parallel scp {} user@server:/path/ ::: *.tar
   ```

3. **Use Docker registry (alternative)**
   ```bash
   # 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