/ Project Handbook

WordPress to Pressable Migration

This page details the process for moving a WordPress site hosted somewhere else to Pressable. Also known as a “lift and shift” migration.

Project Set Up

  • Create Project P2
  • Create Linear project

Prerequisites

  • Administrator access to the WordPress site
  • Access to DNS config or a partner who can alter DNS comfortably (maybe together over a call)

Ideally, we will pull DNS management fully over to us. But either way, the partner needs to be able to access their DNS config, and ideally give us control (with delegate access, where possible). If this doesn’t work, we might need to change DNS together at “switch time” over a call.

Partner Comms

Put together a detailed migration plan of the step-by-step process and share it with the partner. The details and instructions should meet the partner’s level of technical insight and ability to perform actions with their current site, domain, and hosting dashboard. Always offer to hop on a call and do the changes they need to action on a screen share.

Below are the actual steps to set up and move a site to Pressable.

Initial Site Set up

  • Create the Pressable environment using the appropriate CLI command for your setup. ███████████████
  • Clone the site to Pressable using the Pressable Migration plugin. You can re-run this process, which will pull everything, not just delta changes.
  • Disable search engine visibility in wp-admin settings.
  • Install and connect Jetpack to the team account.
  • Check and if necessary clear old Jetpack backup credentials that may have migrated across. ███████████████
  • Install and set up Jetpack Boost.
  • Check existing plugins for obvious signs of editing — e.g., renamed plugin folders from woocommerce-table-rate-shipping to woocommerce-table-rate-shipping-Vm300J, etc.
  • Set the site to a production environment.
  • Add the domain(s) the site will need.

Deploy HQ, GitHub repo setup, test deployment and PHPCS parts are mostly dev tasks.

Deploy HQ set up

  • On DeployHQ for this project, visit Integrations -> New Integration -> HTTP Post -> set Endpoint to ███████████████ and then “Create”
  • Note: don’t change the SFTP credentials as this will cause a deploy failure which will be notified in the team51-bots Slack channel. If you do, update DeployHQ server settings for the project

Repository Set up

  • SFTP into the theme directory, pull the theme files down
  • Pull the repo down from GitHub
  • Alter the .gitignore file so the theme directory will be included e.g.
    !themes/<THEME_NAME>. See ███████████████
  • Commit and push back up the .gitignore and theme files as the initial commit.

Test Deployment (optional)

  • Create a test-feature branch, and add a test-feature file to a new feature branch within the theme
  • Commit and push back up
  • In GitHub, create a PR to merge the feature branch to trunk
  • Merge
  • This should now auto-deploy, verify in the team51-bots Slack channel
  • If it failed, maybe the SFTP password had been changed since the initial environment creation
  • If successful, remove the test file

Run PHPCS on theme code and auto-fix where possible

  • The PHPCS checks have two options depending on your build process—so please refer back to the WordPress Rulesets and use PHPCS in our ███████████████ Handbook page for which process to follow
  • If this changed any files, git pull then commit and push to trunk
  • Leave notes in the readme — e.g.:
Initial Commit Notes PHPCS has been run and PHPCBF fixed 19 issue, 2 errors remain. @<YOURNAME>

Launch checklists

How to use these checklists: When launch planning, add these checklists into GitHub issues in the project repo (or if there is not a GitHub repo, add them to the project P2 or Linear) and check them off as you go through the launch. (███████████████)

The below checklists are a distilled version of our Launch checklists. Consider if the below items are enough, or if you should include the full checklists on a project-by-project basis.

Pre-Launch


- [ ] Share the overall plan with the partner (see above) and drill into the DNS topic as needed.
- [ ] Confirm launch date and time with partner.
- [ ] Confirm dates of any content freeze and/or delta migration.
- [ ] Put date and time of launch on team calendar
- [ ] Confirm a plan for immediate post-launch coverage, especially if you are launching later in your day. Make sure the partner knows when we will be online to provide support for post-launch issues.
- [ ] Start a list of critical things that need to be tested immediately after the launch; key functionality, search, 404s, sitemaps, social sharing, search engine crawlability, analytics tools are recording traffic, etc.
- [ ] Reduce TTLs in advance
- [ ] Inform partner of IP addresses for A record (we aren’t managing their DNS)
- [ ] Confirm that the site being launched uses the proper naming convention: [REPOSLUG]-production.mystagingwebsite.com. Make sure it is connected to the correct branch in GitHub and connected to DeployHQ. Ping the Cascade team with questions.
- [ ] Be sure that our Autoupdate Filter plugin is installed and activated.
- [ ] Confirm VaultPress or Jetpack Backup are in place
- [ ] Confirm access to key login credentials: DNS, wp-admin, CDNs like Cloudfront, hosting control panels, etc.
- [ ] Review the blog RC and confirm the site flagged as a Team 51 site.
- [ ] Flag the site as Team 51 using our internal tool.
- [ ] Confirm our team’s user (or the client, in some cases) own the site on the site’s Report Card.
- [ ] If Jetpack likes need to be retained, note the original blog ID and the blog ID in use on the staging site. If we reconnect to the original blog ID post-launch, the settings below (backups, site flag, etc) will be changed/checked at launch.
- [ ] Footer credit: if hosted on Pressable, add “Hosted by Pressable” link to: https://pressable.com/?utm_source=Automattic&utm_medium=rpc&utm_campaign=Concierge%20Referral&utm_term=concierge
- [ ] Benchmark site performance on the current hosting with WebPageTest.org

The Launch

Follow our ███████████████.

Post Launch / Comms

- [ ] Check both http and https protocols. As there should be a redirect in place for the http.
- [ ] Set up a development environment with current data, theme, plugins, etc. so we can quickly test changes before making them live; connect Jetpack (same process as connecting on live site — plan should match live site); set dev site to discourage search engines/crawlers (via Settings). If on Pressable, here is the CLI command (the Site ID is at the end of the Pressable URL in the control panel): team51 create-development-site –site-id=NNNNNNNN
- [ ] In Zoho, set the Project entry Status to “Launched” and populate the “Completion Date.”
- [ ] Benchmark site performance as before during pre-launch using WebPageTest.org
- [ ] Post a #launched or #migrated note on our team's p2. Add interesting information about any performance improvements from the benchmarking
- [ ] Drop a note about the migration in the team51-highlights-celebrations and team51-thursday-update Slack channels
- [ ] Update relevant P2 posts to note that the site has launched (including updating dev/prod site URLs on project P2).
- [ ] Raise the DNS TTL where applicable.
- [ ] Ensure stats and followers are migrated from the WordPress.com site to the Jetpack site. https://jetpack.com/support/subscription-migration-tool/
- [ ] Is there an existing Akismet key for the site and should it be transferred over to maintain site-specific learning?
- [ ] Verify that Jetpack backups are working, and backing up the DB, code and assets. See this troubleshooting example
- [ ] Have the partner create a WordPress.com account (with 2FA enabled) and connect them to the site through Jetpack: https://getconnectedto.wordpress.com/#getting-started
- [ ] If possible with this site, have a developer remove the local login so a WordPress.com account with 2FA is required to sign in.

Example Migrations

Site-Specific Migration Notes

When partners are using Google Domains, they need to add us as ███████████████ rather than ███████████████ in order for us to be able to access their Google Domains account.

🔍 Search the handbook

All pages