Staging environments and cloning

A staging environment is a second copy of your website or application, on its own domain, that you can break without anyone noticing. When the change works there, 'Clone' copies it over to production.

This article explains what a staging environment is, what is and isn't separate from production, and exactly what 'Clone' does.

What a staging environment is

A project has a production environment, and optionally a staging environment. Each is one running copy of the website or application.

Each environment has its own UNIX user. That means staging has:

• Its own files, in its own home directory.
• Its own database, when the template uses one.
• Its own domain.
• Its own SSH and SFTP login.
• Its own PHP-FPM pool or Passenger app, so its own processes.

Nothing in staging can reach production's files, and a crash in staging doesn't take production down.

The two environments do share the cluster. A staging job heavy enough to load the whole node can still slow production down, so treat a big import or reindex on staging the way you'd treat one on production.

Creating a staging environment

Turn on 'Create Staging Environment' when you create the project, and fill in the 'Staging Domain'. See Creating a project.

Adding staging to a project that doesn't have one isn't something you can do yourself. Contact Cyberfusion support.

Keeping staging private

A staging environment is reachable on the public internet, and search engines will index it if they find it. Two ways to prevent that:

• Basic authentication puts a username and password prompt in front of the whole thing.
• A firewall group on the staging domain router limits it to your office IP addresses.

Switching between environments

On the project page, a 'Production' and 'Staging' switch sits in the left sidebar. Most sidebar items follow it, so 'Crons', 'Databases', 'SFTP & SSH' and the rest always show the environment you have selected.

Check which side the switch is on before you change anything.

Cloning staging to production

'Clone' is in the 'CMS' section of the project sidebar. It only appears once the project has both a production and a staging environment. With staging missing, the item is greyed out and the tooltip says cloning requires both.

What Clone copies

Clone syncs the staging document root to the production document root. That's the files.

Two things follow from this:

• Files are overwritten. A file that differs in production is replaced with the staging version.
• The database is not copied. A change that lives in the database, such as a WordPress setting, a new page, or a Craft entry, does not move to production. Only files do.

Clone runs in one direction only, from staging to production. There's no button to copy production back over staging.

The steps

1. Open 'Clone'. Core compares the two document roots and shows the differences as two file trees, 'Staging' on the left and 'Production' on the right. If nothing differs, it tells you so.
2. Check the comparison, then click 'Continue'.
3. The 'Review clone' step names the exact document root being copied from and the one being copied to, and states that production files will be overwritten.
4. Click 'Clone to production' and confirm.

The comparison step exists so you can catch the common mistake: a file changed directly on production, by a plugin update or an edit over FTP, which the clone is about to throw away.

Before you clone

• Check that production has a recent backup. See All about backups.
• Remember the database doesn't come along. If the change needs a database migration, run it on production yourself after cloning.
• If your deploys already run from Git over SSH, use that instead. Clone is for the case where staging is where the work happened.

Search and replace

For WordPress projects, 'Search & Replace' replaces a string throughout the environment's database.

The usual reason is a domain that's still stored in the database. A WordPress database holds absolute URLs in thousands of rows, so a copy of a site keeps pointing at the domain it came from until you replace it.

Enter the 'Search string' and the 'Replace string', and run it against the environment selected in the sidebar. Check that switch first: running a search and replace against production when you meant staging is not something you can undo without a restore.

Use cases by target group