Staging or shadow is a temporary copy of the site in production. Its main purpose is to provide a safe testing environment without the risk of breaking something in production. The number of shadows that can be opened on a site depends on the level of service plan in use. If your site doesn't have a staging environment yet, contact our customer support. We'll set one up for you!
Warning! If a shadow is unused for an extended period of time, Seravo may delete it without further notice.
Using a Shadow
You can see a list of the shadows available on your site by logging into the site manager, and navigating to Tools > Site Status > Shadows. You can also see the list directly from the drop-down menu in the top bar of the admin panel, which says Now in: PRODUCTION when you are on a production site. The text changes depending on the selected development environment.
Seravo's shadows work with a cookie, so by default the shadow has the same address as the real site in the production environment. This ensures that the settings for plugins and other content on the site work correctly. This is important because some WordPress plugins will stop working or work incorrectly if the site address suddenly changes to something else. To make it clear to the user whether a production site or a shadow site is visible, the top and bottom bars of the control panel have texts and a red warning colour if the shadow site is being viewed.
In the shadow, you can safely make any development experiments and changes you want, and they will not be publicly visible to visitors at the production site. Once you have tested that the change produces the desired result, you can make final changes to the production site. You can return from the shadow to the real site by clicking on the Exit link in the top or bottom bar.
You can also SSH into your shadows and work on them via SSH/SFTP or git. When a new shadow is created you will receive the SSH/SFTP credentials to use with it. You can tell that you’re in a shadow by looking at the WP_ENV environment variable. If you’re in a shadow, it will be staging or testing, depending on what’s applicable in your situation. Your production instance will have a WP_ENV value of production. Environment variables can be checked with wp-list-env command.
The Shadow Cookie
Sometimes you may need to access the shadow environment via browser without logging in to the production site. This can be achieved either by using a separate domain for the shadow, or adding the seravo_shadow cookie to the URL, e.g. https://example.com/?seravo_shadow=456def. The shadow cookie or shadow argument must also be used when using code or command line e.g. with curl or when fetching data from the shadow's WP-JSON API:
curl -iLs https://example.com/test/?seravo_shadow=456def
curl -iLs --cookie "seravo_shadow=456def;path=/" https://example.com/wp-json/wp/v2/
curl -iLs https://example.com/wp-json/wp/v2/?seravo_shadow=456def
Some WordPress plugins depend on the WordPress REST API. If they call this API without including the shadow cookie (e.g. the request does not come from visitors browser but from the server itself or elsewhere), the production instance will be called instead of the shadow. This is not expected behavior and can lead to plugin errors or data loss on production servers.
Moving Data Between the Shadow and the Production
Resetting the Shadow
To ensure that the changes made to the shadow reflect as closely as possible what the changes will do to the production site, it's a good idea to reset the shadow beforehand, which means copying the latest content from production to the shadow.
ATTN! Any data in the shadow is destroyed when it is overwritten with a fresh copy from the production environment.
You can find the option to reset the shadow from the production site’s admin panel under Tools > Site Status > Shadows.
You can also reset the shadow via SSH with wp-shadow-reset command. The command has to be run on the production enrivonment, and also requires you to choose the shadow environment you want to reset, e.g. wp-shadow-reset example_123abc.
Do note, that by default shadow resets do not copy the uploads directory because image files are fetched from production via a proxy. Some themes and plugins may store files in this folder, so those files must be copied or regenerated manually afterwards. If you absolutely need all uploads to physically be in the shadow environment, you can run the wp-shadow-reset command with --full parameter.
Note! If you're using a subdomain in the shadow environment, remember to change the address back to it after each shadow reset.
Publishing the Shadow Environment to Production
Changes made in the shadow environment can also be copied or published to the production environment. This copies all site data (content and database) from the shadow and overwrites the production site. If there is anything in the production environment that you wish to save, take a backup beforehand. In case of online stores, you also might want to consider exporting newest WooCommerce data (e.g. new orders) from the production and importing them to the shadow before publishing it.
Publishing the shadow environment to production is done by running the following command in the production environment:
wp-shadow-pull example_123abc
You can find the name of the shadow environment you wish to publish by running wp-list-env in the shadow (under the CONTAINER field) or from production's admin panel under Tools > Site Status > Shadows.
Note! If your shadow used a custom domain, you must change the address back to the one used in the production after the shadow pull.
Finally, remember to clear all caches by running the command wp-purge-cache.
Copying files with SSH
In some cases you might want not to push the entire shadow to the production as is, but maybe only (some) files just the database. For that purpose you can use commands run over SSH like rsync and database exporting and importing commands. For this you will need to take an SSH connection from production to the shadow, for which you will need to know the SSH port number of it. That can also be found under admin panel's tab Tools > Site Status > Shadows.
The following commands demonstrate how to use rsync via SSH to fetch new files (rsync only transfers files and parts of files that are different). The parameters stand for:
-avsaves the file attributes (owner, time stamp) and prints out a verbose list of all files that changed--delete-afterwill delete all the files from production that did not exist in staging, in effect clearing the obsolete files away--exclude=wp-content/uploadswill omit theuploadsdirectory from being transferred from staging, and from being replaced in productionIn some cases you might want to use
exclude=.gittooThe other options define the SSH port and hostname of the staging instance and the path to the
wordpress/directory
rsync -av --delete-after --exclude=wp-content/uploads -e 'ssh -p 11111' [email protected]:/data/wordpress/ /data/wordpress
[email protected]'s password:
receiving file list ... done
To make sure that all files that exist in the uploads folder in production will remain intact you should transfer them separately with different options:
rsync -av -e 'ssh -p 11111' [email protected]:/data/wordpress/htdocs/wp-content/uploads /data/wordpress/htdocs/wp-content/
If you need to import the database, that can be done after file transfers. However, do note that this will overwrite all data currently in the production database! Make a new database export in staging directly over SSH and import it with one single command:
ssh [email protected] -p 11111 'wp db export -' | wp db import -
Finally, remember to clear all caches by running the command wp-purge-cache.
Differences Between Production and Staging Environment
Unlike production environments, shadows are not automatically backed up. However, backups can be made of shadows manually. This is done using the wp-backup command or the Seravo Plugin in the WordPress admin panel. See more detailed instructions on how to take a backup yourself.
As there are no automatic backups, we recommend that editing and further development of the site is done elsewhere. The development environment should therefore be used for testing, not for saving edits. Read more and check out our developer guide!
The new shadow also has debug messages enabled by default. If you wish, you can hide these messages by editing the wp-config.php file (located in /data/wordpress/htdocs/wp-config.php) as follows:
/**
* For developers: show verbose debugging output if not in production.
*/
if ( 'production' === getenv('WP_ENV') ) {
define('WP_DEBUG', false);
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_LOG', false);
define('SCRIPT_DEBUG', false);
} else { define('WP_DEBUG', false);
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_LOG', false);
define('SCRIPT_DEBUG', false);
Please note that it is easy to export only code changes from local to shadow and from shadow to production, as the WordPress database model does not support any automation for copying individual content or setting changes from one database to another. If the entire WordPress database is copied from the shadow to production, the production database will be overwritten and essential data may be lost.