Extensions & Integrations

Provides a way to sync all content for a site, or all sites, between two environments. Our hosting customers receive this automatically as part of our hosting CLI. Self-hosted Pro and Assembly customers can use this command line tool in their own environment.
Upgrade your project
This is a premium module and requires a Pro license. More here.

@apostrophecms-pro/sync

For our hosting customers

This module provides the underlying implementation of content sync via S3 and mongodb for Apostrophe single-site and multisite projects hosted by the ApostropheCMS team. See assembly-cloud-tools (for internal use) and assembly-cli (for customer use) for examples of how to leverage it. There is no need to use this module directly.

For self-hosted customers

For self-hosted customers with Apostrophe Pro and Assembly licenses, this module also provides the apostrophe-sync command, which allows access to the same content sync capabilities in a way that works outside of our hosting environment.

Self-hosted installation

Our hosting customers do not need this command and should not install it.

npm install -g @apostrophecms-pro/sync

Self-hosted usage

⚠️ It is NOT possible to undo these operations. Use these commands with great care. In particular, think carefully before using sync up.

Syncing content up to the remote, or down to your local workstation

First set the required environment variables:

# For all projects
#

# For single site this must include the database name
export APOS_REMOTE_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE/project"
# For multisite leave off the database name
export APOS_REMOTE_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"

# For media
export APOS_REMOTE_S3_BUCKET="yourbucket"
export APOS_REMOTE_S3_KEY="yourkey"
export APOS_REMOTE_S3_SECRET="yoursecret"
export APOS_REMOTE_S3_REGION="yourregion"

# For multisite projects only
#
# Must point to your dashboard site (not just the domain, must include dashboard.)
export APOS_REMOTE_DASH_HOSTNAME=dashboard.yourproject.com
# Must be the name of your dashboard database, NOT the MongoDB connection URI.
# See shortnamePrefix in app.js for the first part, a3ab- is just an example
export APOS_REMOTE_DASH=a3ab-dashboard
# Must match the value of the ENV environment variable in the remote environment
export APOS_REMOTE_ENV=prod

Then you may use the commands in that same terminal:

# sync down FROM the remote TO your workstation
apostrophe-sync down
# sync up TO the remote FROM your workstation
apostrophe-sync up
# sync just one site in a multisite Assembly project
apostrophe-sync down --site=shortNameOfSite
# sync just one site in a multisite Assembly project
apostrophe-sync up --site=shortNameOfSite

Syncing content between two remote environments

# Provide separate "FROM" and "TO" credentials for your separate environments
export APOS_FROM_DASH_HOSTNAME=dashboard.yourproject.com
export APOS_FROM_DASH="a3ab-dashboard"
export APOS_FROM_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"
export APOS_FROM_S3_BUCKET="yourbucket"
export APOS_FROM_S3_KEY="yourkey"
export APOS_FROM_S3_SECRET="yoursecret"
export APOS_FROM_S3_REGION="yourregion"
export APOS_FROM_ENV=prod

export APOS_TO_DASH_HOSTNAME=dashboard.staging.yourproject.com
export APOS_TO_DASH="a3ab-dashboard"
export APOS_TO_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"
export APOS_TO_S3_BUCKET="yourbucket"
export APOS_TO_S3_KEY="yourkey"
export APOS_TO_S3_SECRET="yoursecret"
export APOS_TO_S3_REGION="yourregion"
export APOS_TO_ENV=staging

# Sync between the FROM and TO environments, based on the
# environment variables you set above
apostrophe-sync between
# Sync just one site (for multisite Assembly projects)
apostrophe-sync between --site=shortNameOfSite

"What does APOS_REMOTE_ENV do?"

In multisite projects, Apostrophe stores hostnames calculated to suit each deployed environment in separate properties. Apostrophe determines which hostnames to use via the ENV environment variable which should already be configured in your deployed environments. When syncing content between environments, this command needs to know the environment name in order to copy content from one set of properties to the other during the sync. If you are unclear on this part feel free to consult our team.

For those not using S3

Clients not using S3 may still leverage this module to sync databases. To skip the media sync, use:

--skip-files

Additional command line options

To skip the database sync, for instance because you already completed it but need to retry the S3 sync, you may use:

--skip-db

To skip syncing document content versions in order to save time during database sync, use:

--skip-versions

⚠️ --skip-versions does not leave out any necessary content for the live site, but does prevent rollback to earlier versions of a given document.

Updated

less than 1 month ago

Version

1.1.0

Report a bug