README

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

      bash   
  1 # For all projects  2 #  3 ​  4 # For single site this must include the database name  5 export APOS_REMOTE_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE/project"  6 # For multisite leave off the database name  7 export APOS_REMOTE_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"  8 ​  9 # For media  10 export APOS_REMOTE_S3_BUCKET="yourbucket"  11 export APOS_REMOTE_S3_KEY="yourkey"  12 export APOS_REMOTE_S3_SECRET="yoursecret"  13 export APOS_REMOTE_S3_REGION="yourregion"  14 ​  15 # For multisite projects only  16 #  17 # Must point to your dashboard site (not just the domain, must include dashboard.)  18 export APOS_REMOTE_DASH_HOSTNAME=dashboard.yourproject.com  19 # Must be the name of your dashboard database, NOT the MongoDB connection URI.  20 # See shortnamePrefix in app.js for the first part, a3ab- is just an example  21 export APOS_REMOTE_DASH=a3ab-dashboard  22 # Must match the value of the ENV environment variable in the remote environment  23 export APOS_REMOTE_ENV=prod  

Then you may use the commands in that same terminal:

      bash   
  1 # sync down FROM the remote TO your workstation  2 apostrophe-sync down  3 # sync up TO the remote FROM your workstation  4 apostrophe-sync up  5 # sync just one site in a multisite Assembly project  6 apostrophe-sync down --site=shortNameOfSite  7 # sync just one site in a multisite Assembly project  8 apostrophe-sync up --site=shortNameOfSite  

Syncing content between two remote environments

      bash   
  1 # Provide separate "FROM" and "TO" credentials for your separate environments  2 export APOS_FROM_DASH_HOSTNAME=dashboard.yourproject.com  3 export APOS_FROM_DASH="a3ab-dashboard"  4 export APOS_FROM_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"  5 export APOS_FROM_S3_BUCKET="yourbucket"  6 export APOS_FROM_S3_KEY="yourkey"  7 export APOS_FROM_S3_SECRET="yoursecret"  8 export APOS_FROM_S3_REGION="yourregion"  9 export APOS_FROM_ENV=prod  10 ​  11 export APOS_TO_DASH_HOSTNAME=dashboard.staging.yourproject.com  12 export APOS_TO_DASH="a3ab-dashboard"  13 export APOS_TO_MONGODB_URI="mongodb://YOUR-MONGODB-OR-ATLAS-URI-GOES-HERE"  14 export APOS_TO_S3_BUCKET="yourbucket"  15 export APOS_TO_S3_KEY="yourkey"  16 export APOS_TO_S3_SECRET="yoursecret"  17 export APOS_TO_S3_REGION="yourregion"  18 export APOS_TO_ENV=staging  19 ​  20 # Sync between the FROM and TO environments, based on the  21 # environment variables you set above  22 apostrophe-sync between  23 # Sync just one site (for multisite Assembly projects)  24 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.