Download the PHP package jorisnoo/craft-remote-sync without Composer

Remote Sync for Craft CMS

A Craft CMS module that syncs databases and storage files between remote and local environments over SSH and rsync.

Features

• Pull a remote database and storage files to your local environment
• Push your local database and files to a remote (disabled per remote by default)
• A plan preview before anything is changed, with a --dry-run that stops after it
• Backups taken automatically before either side's database is overwritten
• A single SSH round-trip to detect the atomic layout, a compatible PHP binary, and rsync
• File deletion is opt-in: the preview shows what --delete would remove, but nothing is deleted unless you ask
• doctor to check prerequisites and prune to clean up old snapshots
• Support for multiple named remotes and atomic deployments (current/ symlink)

Requirements

Run craft remote-sync/doctor to check everything is in place.

Installation

Register it as a module in config/app.php:

The bootstrap entry is required so the module registers its console controllers.

Configuration

Copy the config file into your project and edit it:

Each remote needs a host (an SSH connection string, optionally user@host:port) and a path (the Craft app root on the server). For an atomic deployment, point path at the release parent; a /current symlink is detected and used automatically. Pushing is refused unless push is true.

The env var names follow REMOTE_SYNC_{REMOTE}_{KEY}, so a staging remote reads REMOTE_SYNC_STAGING_HOST and REMOTE_SYNC_STAGING_PATH.

Usage

Pull (remote → local)

Without flags it asks which remote and what to sync, verifies the host key, probes the remote, prints the plan, and asks for confirmation. For the database it backs up your local database (pre-pull-*), takes a snapshot on the remote, downloads and restores it, then runs craft up and clears caches. For files it rsyncs each configured path.

Push (local → remote)

Push requires the remote to have push enabled, always asks for a typed yes confirmation, and needs an explicit scope when run non-interactively. It backs up the remote database (pre-push-*) before uploading and restoring your local one, then runs craft up on the remote.

Doctor

Checks local tools and, per remote, the host key, application path, PHP binary, and rsync.

Prune

Deletes old snapshots created by this module, keeping the newest --keep. It leaves snapshots it did not create alone unless --all is given.

Backups and snapshots

Two kinds of database file are involved:

• A transfer snapshot (remote-sync-*) is the data being moved. The copy on the remote is always cleaned up, even if you interrupt with Ctrl+C. On a pull, the copy downloaded to your machine is kept.
• A backup (pre-pull-* locally, pre-push-* on the remote) is a safety copy taken before a side is overwritten. It is kept, so you can roll back with craft db/restore.

Both live in Craft's standard storage/backups directory. Skip the safety backup with --no-backup, and delete the downloaded snapshot once it has been imported with --discard-snapshot. Kept snapshots are subject to remote-sync/prune, which keeps the newest five by default.

A push cleans up both copies of its transfer snapshot, local and remote. Only a pull leaves one behind.

A pull or push refuses to run when the local environment is production, unless you set allow_production to true.

Versioning

This module is maintained on separate branches for each major Craft CMS version:

Upgrading from 2.x? See UPGRADING.md for the config and command changes.

License

MIT — see LICENSE for details.

Maintainer releases

See RELEASING.md for versioning, changelog entries and the release command.