Moving a WordPress instance by hand

Over the years I’ve migrated a lot of WordPress sites. Although there are plugins that can take care of it, I have yet to find a more efficient way than just doing it by hand. The following is my recipe for migrating WordPress instances.

In the example we move a site to our local development environment.

Prerequisites

• Shell (usually SSH) access to the server that runs the WordPress instance
• PHP CLI (sudo apt install php-cli)
• WP-CLI

Exporting the database

The quickest way is to use wp-cli:

cd public_html
wp db dump example.com.sql

If that doesn’t work, here’s the manual way:

cd public_html
# Find database credentials
grep DB_ wp-config.php
# Create a database dump
mysqldump somedb -u someuser -p'somepassword' > example.com.sql

Archiving the website

Make a tarball of the site’s files:

tar czf example.com.tgz public_html

If it’s only for testing and you’re in a hurry, exclude the WP Uploads directory:

tar czf example.com.tgz --exclude=**/wp-content/uploads/* public_html

Now copy the tarball over to your machine.

Setting up local environment

1. Unpack the WordPress instance:
   tar xzf example.com.tgz
2. Update database credentials in wp-config.php
   For local development, I usually just take user ‘root’ with an empty password (the Gods of Security frown upon me)
3. Create and import the database, e.g.:
   sudo mysqladmin create example_com
cd public_html
wp db cli < example.com.sql
4. To not need HTTPS locally:
   a. Remove any line containing “FORCE_SSL_ADMIN” from wp-config.php
   b. Remove or rename (= deactivate) any plugin (from wp-content/plugins) that forces ssl, for instance ‘really-simple-ssl’
5. Replace your WordPress base URL using wp-cli:
   wp search-replace https://example.com http://localhost:8080
6. Run the local development server:
   wp server --port=8080

You should now be able to access the WordPress site by visiting http://localhost:8080 !

Optional, but handy

Create an admin user for yourself:
wp user create myadmin [email protected] --role=administrator --user_pass=admin

Troubleshooting

If connecting to the database fails, it could be that an empty password is not accepted. As using root with an empty password is a bit of a hack, here’s another hack to make it work for newer versions of MySQL/MariaDB. Obtain a root MySQL shell and execute:

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '';
FLUSH PRIVILEGES;

Further (necessary) tweaking

See WordPress development tricks