Asset Sync Plugin

Synchronize assets between filesystems in Craft CMS, allowing you to migrate from local storage to cloud storage (e.g., Cloudflare R2) while preserving all asset metadata and database references.

Features

• Sync assets from one filesystem to another
• Preserves all asset metadata (IDs, titles, alt text, custom fields, etc.)
• Progress tracking with visual feedback
• Dry-run mode for testing
• Error handling and reporting
• Resume capability (skips already-copied files)

Installation

The plugin is located in plugins/flowsa/asset-sync/ and will be automatically loaded by Craft CMS.

Usage

Basic Sync Command

ddev craft asset-sync/sync --volume=<volume-handle> --destination-filesystem=<filesystem-handle>

Command Options

• --volume (required): The handle of the asset volume to sync
• --destination-filesystem (required): The handle of the target filesystem
• --dry-run: Test mode - shows what would be copied without actually copying
• --force: Skip confirmation prompt

Example: Sync Local Files to Cloudflare R2

# Preview what will be synced
ddev craft asset-sync/sync --volume=files --destination-filesystem=cloudFiles --dry-run

# Execute the sync
ddev craft asset-sync/sync --volume=files --destination-filesystem=cloudFiles

# Execute without confirmation prompt
ddev craft asset-sync/sync --volume=files --destination-filesystem=cloudFiles --force

Migration Workflow

1. Ensure R2 filesystem is configured

   • Verify R2 credentials in .env
   • Check filesystem config in config/project/project.yaml

2. Run dry-run to preview

   ddev craft asset-sync/sync --volume=files --destination-filesystem=cloudFiles --dry-run

3. Execute the sync

   ddev craft asset-sync/sync --volume=files --destination-filesystem=cloudFiles

4. Update volume configuration

   • Edit config/project/volumes/<volume-uid>.yaml
   • Change fs: files to fs: cloudFiles

5. Apply project config

   ddev craft project-config/apply

6. Verify assets are accessible

   • Check asset URLs in control panel
   • Test image transforms
   • Verify file downloads

7. Keep local files as backup until fully verified

Technical Details

What Gets Synced

• All asset files from the source filesystem
• Directory structure is preserved
• File paths remain identical

What Does NOT Change

• Asset IDs remain the same
• Database records are unchanged
• Asset metadata (alt text, focal points, custom fields) is preserved
• Asset URLs update automatically after volume filesystem change

Resume Capability

The sync automatically skips files that already exist in the destination filesystem, allowing you to resume an interrupted sync or re-run the command safely.

Troubleshooting

"Volume not found"

• Check that the volume handle is correct using: ddev craft volumes

"Filesystem not found"

• Check available filesystems in config/project/project.yaml under the fs: section

Files not accessible after sync

• Verify R2 credentials are correct
• Check filesystem URL configuration
• Ensure bucket permissions are set correctly

Support

For issues or questions, contact Flow Communications at http://www.flowsa.com