# Harbor 0.4.0 Migration Guide

> **Note**: This document covers the one-time file-system migration introduced in Harbor 0.4.0. If you're on Harbor ≥ 0.4.0, this migration has already been completed and you don't need to do anything here.
>
> The current `harbor migrate` command is a **config schema migration tool** that updates your `.env` file when new config keys are introduced between Harbor releases. It supports `--dry-run` and `--target <version>` flags. Run `harbor migrate --help` for details.

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

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

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

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

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

```bash
harbor down
```

This ensures no services are writing to files during migration.

#### Step 3: Preview the Migration

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

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

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

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

```bash
harbor migrate
```

### `harbor migrate --dry-run`

Preview what would be migrated without making any changes.

```bash
harbor migrate --dry-run
```

### `harbor migrate --force`

Skip all confirmation prompts (useful for automated deployments).

```bash
harbor migrate --force
```

### `harbor migrate --rollback=<backup-dir>`

Restore files from a previous migration backup.

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

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

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

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

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

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