Extensions & Integrations
Content Sync
@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.