Create a staging site and push it to production

A staging site is a second hosting on the same node that holds a copy of the live site’s files and database. You change and test it there, then push it back. The push takes a backup of production first.

Before you start

• WordPress is installed on the production hosting and the hosting is active.
• You hold the Manage WordPress (plugins, staging, …) permission for the hosting and the Create hostings permission, because the staging site is a new hosting. The built-in Customer role has the first but not the second.
• The staging hostname resolves to this server. By default it is staging.<domain>. Create a DNS record for it, or rely on a wildcard record for *.<domain>.
• The staging hosting is created on the same node as production.
• Production has a recent backup you trust. Open the hosting’s Backups tab and check that the newest entry shows the state ok.

Steps

Create the staging site

1. Open Hostings in the sidebar, click the production hosting, and open the WordPress tab.
2. Open Tools, then Staging site. The row reads “a test copy to try updates on” until a staging site exists.
3. In Staging hostname, leave the default staging.<domain> or enter another name. It must differ from the production domain.
4. Click Create staging and confirm Create staging copy.

When a staging site already exists, the button reads Refresh staging, and creating is refused with “already exists — push or delete it first”. To start over, delete the staging hosting, then create it again.

Hyperion backs up production, creates a new hosting with the same PHP version, database engine and kind, restores the backup into it, hands the files to the new hosting’s system user and rewrites the site URL in the database from the production host to the staging host with wp search-replace. The browser then opens the new staging hosting’s page.

Work on the staging site

Open the staging hosting like any other hosting: it appears in the Hostings list under its own name, with its own WordPress tab, files and database. Use it to try plugin, theme and core updates.

Push staging over production

Before you push staging to production

A push restores the staging site’s files and database over the live site. The live site’s database is replaced. Live files are overwritten with the staging versions, and files that exist only on the live site are left where they are. Anything visitors changed on the live site since you created the staging copy, such as orders, comments and uploaded media, is lost from the database.

Hyperion backs up both sites immediately before the push, so there are two new entries, one on each site. To confirm a usable backup exists afterwards, open the production hosting’s Backups tab and look for a new entry with the state ok timed immediately before the push. To undo the push, restore that backup from the same tab. A push cannot be undone any other way.

1. On the production hosting’s WordPress tab, open Tools, then Staging site. The Push staging → production and Open staging ↗ buttons appear once a staging site exists.
2. Click Push staging → production and confirm with Push to production.
3. You land on a job page that follows the push. The job reads “Pushing staging → production…” and ends with “Staging pushed to production.”

After the restore, Hyperion hands the files back to the production system user and rewrites the URLs in the database from the staging host back to the production host.

Check that it worked

• After creating: the Hostings list shows the staging hostname, and Open staging ↗ loads the copy.
• After pushing: Background jobs shows the job as finished, and the production site shows the staging changes. The production hosting’s Backups tab lists the backup taken before the push.

If it fails

• “<staging host> already exists — push or delete it first”: a hosting with that name exists. Create does not refresh an existing staging site. Push it to production, or delete the staging hosting and create it again.
• “<staging host> doesn’t resolve to this server yet”: add the DNS record (or a *.<domain> wildcard) pointing at this server, then retry.
• “staging hostname must differ from the production domain”: enter a different name.
• “staging domain invalid”: the hostname is not a valid domain name.
• “creating a staging site needs the hosting-create permission”: ask an administrator to create it, or to grant the permission.
• “no <staging host> to push — create a staging site first”: the staging hosting does not exist on this node.

Related

• Restore a site from a backup
• Create a website