1.3 Migration Guide

Harbor 0.4.0 Migration Guide

Overview

Harbor 0.4.0 introduces a breaking change to improve repository organization. All service-related files have been moved from the repository root to a dedicated services/ directory.

What Changed

Before (< 0.4.0):

harbor/
  compose.yml
  compose.ollama.yml           # Compose files at root
  compose.x.ollama.webui.yml   # Cross-files at root
  .env
  ollama/                      # Service directories at root
    override.env
    modelfiles/
  webui/
    override.env

After (≥ 0.4.0):

harbor/
  compose.yml                  # Base compose stays at root
  .env                         # Shared env stays at root
  services/                    # NEW: All service files here
    compose.ollama.yml
    compose.x.ollama.webui.yml
    ollama/
      override.env
      modelfiles/
    webui/
      override.env

---

Do I Need to Migrate?

Fresh Installation (v0.4.0+)

No action needed. If you're installing Harbor v0.4.0 or later for the first time, everything is already in the correct structure.

Existing Installation (< v0.4.0)

Yes, you need to migrate if you have:

• Service directories at the Harbor root (e.g., ./ollama/, ./dify/)
• Compose files at the root (e.g., ./compose.ollama.yml)
• Custom service configurations or data in service directories

How to Check

Run the following to check your current structure:

# If this shows service directories, you need to migrate
ls -d */ | grep -v "app\|docs\|routines\|scripts\|profiles\|shared\|harbor\|tools\|skills\|services\|node_modules\|dist"

# If this shows compose files, you need to migrate
ls compose.*.yml 2>/dev/null | grep -v "^compose.yml$"

---

Migration Process

Harbor provides an automated migration tool to safely move your files.

Quick Migration

# Preview what will be migrated (recommended first step)
harbor migrate --dry-run

# Run the migration
harbor migrate

# If something goes wrong, rollback
harbor migrate --rollback=.migration-backup-<timestamp>

Step-by-Step Migration

Step 1: Backup Your Data

The migration tool automatically creates backups, but it's good practice to create your own:

# Create a manual backup
tar -czf harbor-backup-$(date +%Y%m%d).tar.gz .env services/ ollama/ webui/ dify/ # ... your services

⚠️ Warning about Large Data:

The automatic backup will copy all data in service directories, including:

• Model files (Ollama models, ComfyUI models, etc.)
• Database files
• Cache directories
• Any other large data stored in service folders

If your service directories contain gigabytes of data, the backup process will:

• Take significant time
• Consume significant disk space
• Duplicate data unnecessarily

Recommendations for large installations:

Since migration only moves directories (not modifying them), you have options:

1. Skip automatic backup and manually move directories back if needed
2. Stop large-data services and exclude their directories from manual backup
3. Use Docker volumes for large data (recommended for production)

# Check directory sizes before migrating
du -sh ollama/ webui/ dify/ # ... your services

# If sizes are large (>5GB total), consider creating a lightweight backup
# that excludes model files and data directories:
tar -czf harbor-backup-$(date +%Y%m%d).tar.gz \
  --exclude='*/models' \
  --exclude='*/cache' \
  --exclude='*/data' \
  .env services/ ollama/override.env webui/override.env # ... just configs

Step 2: Stop Running Services

harbor down

This ensures no services are writing to files during migration.

Step 3: Preview the Migration

harbor migrate --dry-run

Review the output carefully. It will show:

• Service directories to be moved
• Compose files to be moved
• Total count of each

Example output:

Migration Plan:
  Service directories to move: 15
  Compose files to move:       45

Service directories:
    - ollama/
    - webui/
    - dify/
    ...

Compose files:
    - compose.ollama.yml
    - compose.webui.yml
    - compose.x.ollama.webui.yml
    ...

Step 4: Run the Migration

If the dry-run looks correct, proceed with the actual migration:

harbor migrate

The migration will:

1. ✅ Run pre-flight checks
2. ✅ Create a timestamped backup (.migration-backup-<timestamp>)
3. ✅ Move service directories to services/
4. ✅ Move compose files to services/
5. ✅ Verify the migration succeeded

Step 5: Test Your Services

After migration, test that everything works:

# Check that services are listed
harbor ls

# Start a service to verify it works
harbor up ollama

# Check another service
harbor up webui

Step 6: Clean Up Backup (Optional)

Once you've confirmed everything works, you can remove the backup:

# List backups
ls -d .migration-backup-*

# Remove backup after confirming everything works
rm -rf .migration-backup-<timestamp>

---

Migration Command Reference

harbor migrate

Run the migration with interactive confirmation.

harbor migrate

harbor migrate --dry-run

Preview what would be migrated without making any changes.

harbor migrate --dry-run

harbor migrate --force

Skip all confirmation prompts (useful for automated deployments).

harbor migrate --force

harbor migrate --rollback=<backup-dir>

Restore files from a previous migration backup.

# List available backups
ls -d .migration-backup-*

# Rollback from a specific backup
harbor migrate --rollback=.migration-backup-1234567890

---

Troubleshooting

Backup Taking Too Long

If the automatic backup is taking a very long time, it's likely copying large model files or datasets. The migration script will show warnings for directories larger than 100MB.

Solutions:

1. Let it complete (safest option)
2. Cancel (Ctrl+C) and manually backup only configuration files
3. Since migration only moves directories, you can restore by simply moving them back if something goes wrong

Migration Failed

If the migration fails partway through:

1. Check the error messages in the output
2. The backup is preserved at .migration-backup-<timestamp>
3. Rollback: harbor migrate --rollback=.migration-backup-<timestamp>
4. Fix the issue and try again

Services Not Starting After Migration

# Check if services are detected
harbor ls

# Check compose file generation
harbor cmd -h

# Try rebuilding
harbor build <service>
harbor up <service>

Backup Directory Not Found

If you need to manually restore:

# Assuming backup is .migration-backup-1234567890
cd .migration-backup-1234567890

# Restore service directories
cp -r service-dirs/* ../

# Restore compose files
cp compose-files/* ../

# Remove the migrated files from services/
rm -rf ../services/ollama ../services/webui # ... etc

"services/ directory already exists"

This is normal. The migration script checks for existing files and skips them. If you have a partial migration, you can:

1. Complete it by running harbor migrate again
2. Or manually move remaining files

Custom Modifications Lost

If you had custom modifications to compose files or service configs:

1. Check the backup: .migration-backup-<timestamp>/
2. Compare with current files
3. Reapply your changes to the new locations

---

What Changes After Migration

File Paths

All relative paths in compose files now reference services/:

# Old: ./ollama/override.env
# New: ./services/ollama/override.env

services:
  ollama:
    env_file:
      - ./.env                        # Unchanged (from merged compose)
      - ./services/ollama/override.env  # Now includes services/
    volumes:
      - ./services/ollama/modelfiles:/modelfiles  # Now includes services/

User Data Location

Your service data remains in the same relative location:

# Old: ./ollama/modelfiles/
# New: ./services/ollama/modelfiles/

# The data itself hasn't moved, just its parent directory