Skip to content

USAGE.md

Latest commit

 

History

History
167 lines (120 loc) · 3.97 KB

USAGE.md

File metadata and controls

167 lines (120 loc) · 3.97 KB

Asset Sync Plugin - Quick Start Guide

Installation

The plugin has been installed and is ready to use. It's located at plugins/flowsa/asset-sync/.

Current Configuration

Your site currently has:

  • Volume: "Files" (handle: files)
  • Local Filesystem: files (@webroot/uploads/files)
  • R2 Filesystem: cloudFiles (Cloudflare R2, already configured)
  • Assets Found: 9,166 files

How to Migrate to Cloudflare R2

Step 1: Preview the Sync (Dry Run)

Test what will happen without actually copying files:

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

This will:

  • Show exactly what files will be copied
  • Display progress as it scans
  • Not modify any files
  • Report any errors it finds

Step 2: Execute the Real Sync

Once you're confident, run the actual sync:

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

You'll see:

  • Configuration summary
  • Asset count (9,166 files)
  • Confirmation prompt
  • Real-time progress bar
  • Final report with copied/skipped/failed counts

Note: This may take some time with 9,166 assets. The sync will:

  • Skip files that already exist in R2
  • Continue from where it left off if interrupted
  • Log all errors for review

Step 3: Switch the Volume to Use R2

After successful sync, update the volume configuration:

# Edit the volume config file
nano config/project/volumes/files--c99ad3ba-ce06-4638-953f-6723cc4ab85d.yaml

# Change line 94:
# FROM: fs: files
# TO:   fs: cloudFiles

Or use this command:

sed -i '' 's/fs: files/fs: cloudFiles/' config/project/volumes/files--c99ad3ba-ce06-4638-953f-6723cc4ab85d.yaml

Step 4: Apply the Configuration

ddev craft project-config/apply

Step 5: Verify Everything Works

  1. Visit the control panel and check assets load correctly
  2. Test asset URLs in your frontend
  3. Verify image transforms work
  4. Check that new uploads go to R2

Step 6: Backup & Cleanup

Once verified (wait a few days):

  1. Keep local files as backup for a while
  2. Monitor for any issues
  3. Eventually remove local files to save space

Command Options

Required Flags

  • --volume=<handle> - The asset volume to sync (e.g., files)
  • --destination-filesystem=<handle> - Target filesystem (e.g., cloudFiles)

Optional Flags

  • --dry-run - Preview mode, no files copied
  • --force - Skip confirmation prompt

Short Aliases

  • -v for --volume
  • -d for --destination-filesystem
  • -n for --dry-run
  • -f for --force

Examples

# Preview sync
ddev craft asset-sync/sync -v files -d cloudFiles -n

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

# Execute without confirmation (automated scripts)
ddev craft asset-sync/sync -v files -d cloudFiles -f

What Gets Synced

✅ Included:

  • All asset files
  • Directory structure
  • File paths (stay identical)

✅ Preserved:

  • Asset IDs
  • Asset metadata (titles, alt text, etc.)
  • Custom field values
  • Focal points
  • Database references

❌ Not Synced:

  • Transforms (regenerated on-demand)
  • Temporary files

Troubleshooting

Sync Takes Too Long

With 9,166 assets, this is normal. The sync can be interrupted and resumed - it skips files already in R2.

Files Not Accessible After Switch

  1. Verify R2 credentials in .env
  2. Check R2 bucket name matches config
  3. Ensure bucket permissions allow public access
  4. Check filesystem URL configuration

Some Files Failed

Check the error report at the end of sync. Common issues:

  • Missing source files (already deleted)
  • Permission issues
  • Network timeouts (re-run to resume)

Rollback

If you need to switch back to local storage:

# Edit volume config
sed -i '' 's/fs: cloudFiles/fs: files/' config/project/volumes/files--c99ad3ba-ce06-4638-953f-6723cc4ab85d.yaml

# Apply changes
ddev craft project-config/apply

Support

For issues or questions, contact Flow Communications.