June 23, 2017
I’m delaying publishing my final write-up on The Condon Project until Chris is ready to reveal the site. In the meantime I ran into problem in another project that I couldn’t find a tutorial for, so I’m going to try and write one. This is that tutorial.
I recently helped a client get a soon-to-be revealed WordPress site off the ground. This particular client already owned a domain name and had hosting, and just wanted to add a new site to a sub-domain. I needed to set up said subdomain, install WordPress (client’s preferred CMS), install the plugins they needed, and do some light theme customization.
I ran into a problem getting one particular plugin to execute a particular behavior I was looking for, and I needed to dive into the source code to see what was up. There was just one hangup—the site was already live on a production server. Because I (in true newbie fasion) underestimated the complexity of a feature, I was stuck in a situation where the website was live and any changes I tried to make to the plugin’s code could potentially break the site.
What I needed to do was simluate the server as closely as I could, and clone the site onto my computer. What follows is a step-by-step guide on how to set up a local development environment, and clone a live WordPress site into it. This tutorial makes a few assumptions:
- You’re comfortable using a Bash terminal in a Unix-Based Operating System (Linux or macOS).
- You have a live WordPress site and how to use your web hosts’ FTP (or have some way to transfer the files that make up your site)
- You are using either Windows, macOS, or a Linux distribution based on Ubuntu
- (Optional) You have some experience with Apache
After following along with this tutorial, you will have:
- Started a Virtual Machine using VirtualBox
- Copied the files from your website onto your local machine
- Installed and configured the Apache web server to serve files locally
- Installed PHP to run WordPress
- Recreated your site’s database on your computer using phpMyAdmin
VirtualBox is a tool used to start up virtual machines on your computer. A virtual machine is an emulator that lets you run an entirely isolated OS within your computer. The files you install and programs you run are sandboxed so you can’t break anything on your system from inside of them. This is perfect for when you need to simulate the environment on your webserver but can’t risk making breaking changes to your live site.
Installing VirtualBox on Windows or macOS is easy. Simply download the .exe (Windows) or .dmg (macOS) from the link above and install it like normal. For Linux users, you can either follow the link above and download the tar file appropriate for your distro, or you can install via your distrubution’s software manager. To install via the software manager, first open up a Terminal (Ctrl+Alt+T) and type:
sudo apt-get update && sudo apt-get dist-upgrade -y
This will ensure your distro’s package repository listings are up to date, and you have all major OS upgrades. Next open up your distribution’s software manager. For Ubuntu this is Ubuntu Software, for Linux Mint this is the Software Manager. For other distros, please consult your respective distro’s documentation.
In your software manager, search for “VirtualBox”. Depending on your distro, your search may return several results. If this is the case, find the one simply called “VirtualBox” and install that one. The others are specific components for niche uses.
Once you have installed VirtualBox you will need to download the installation file for the operating system on your server. In my case I need Ubuntu 16.04 which I found here. With the OS install file on a USB drive, you can open up VirtualBox, click “New” to start a new virtual machine, and follow the on screen instructions. For my virtual machine, I chose to limit the available memory to mimic a server environment in which my application would only have access to 1MB of RAM. Your hard drive size is up to you, but I would opt large enough to house multiple projects. You can always change the options later.
Now, you should have a virtual machine running Ubuntu. If all went well, you’ll see something like this in your VirtualBox window:
Alright! Our Virtual Machine is up and running! Time to get something onto it.
Copying the Files
Once you are in your Virtual Machine, open up a web browser. Log in to your web host’s FTP client and copy the files from your domain onto your VM’s hard drive. If your host doesn’t allow downloading of files directly you can use an app like FileZilla to log into your your host and clone the files.
The destination of these files should be something like:
/var/www/html/[your project’s name]/
Apache, which we’ll be installing in the next phase, serves files by default from here. Placing your project’s files inside a folder in this directory will just make life easier later on.
It’s likely that a live WordPress site will have thousands of files, so you should definitely start this process first so it can run in the background.
Installing Apache, MySQL, and PHP
Wordpress depends on having a few other things on your system before it can run. Namely those are Apache (server that listens for requests and serves files), MySQL (popular database), and PHP (interpreter for the PHP programming language). These three things are very frequently installed on Ubuntu servers. So frequently the name LAMP—Linux, Apache, MySQL, PHP—is commonly used to refer to this software stack.
Ubuntu.org has a simple tutorial, but if you want to save a click here’s the rundown. All of these should be executed in a terminal window inside your virtual machine:
sudo apt-get update sudo apt-get install apache2 sudo apt-get install mysql-server mysql-client sudo apt-get install php libapache2-mod-php
Line 1 updates package lists
Line 2 installs the Apache web server
Line 3 install MySQL. During this step, you will be prompted to enter a password for the “root” MySQL user for your machine. Remember this password.
Line 4 installs PHP. This is a departure from the Ubuntu.org tutorial, because the recommended requirements for WordPress have recently changed. By default Ubuntu should install PHP 7.0. If your web host still uses an older version of PHP, consider writing them and asking them to upgrade.
Once you have those installed, you’ll need to restart Apache to make sure it’s talking to MySQL and PHP correctly.
sudo service apache2 restart
will do the trick. To check and see if Apache is running, open a new tab in your browser and go to either
127.0.0.1. You should see this:
This is Apache’s default home page, and contains info about how to configure the program how you want. You’ll notice the first paragraph points you to the location of the file “index.html,” which is what is actually being displayed in your browser.
We can also use the browser to make sure PHP installed correctly. Navigate to the folder listed above (
/var/www/html/) and create a new file called “check.php.” In this new file, type the following code:
<?php phpinfo(); ?>
Once you’ve saved the file, open a new browser tab and go to
localhost/check.php. You should see a long page of very detailed information about your PHP installation. As long as it’s version 7.0.0 or higher, everything is fine.
Apache's main configuration file can be found at
/etc/apache2/apache2.conf. Open up this file in a text editor and look for a section containing the following:
<Directory /var/www/> Options Indexes FollowSymLinks AllowOverride None Require all granted </Directory>
There should be several
Directory tags. These tell Apache how to interact with various folders on your computer. Add this to the bottom of that section:
<Directory /var/www/html/[your project's name]/> Options Indexes FollowSymLinks AllowOverride All Require all granted </Directory>
This tells Apache to allow custom permissions to be set for your project’s folder via a file called
.htaccess. This file doesn’t exist yet. WordPress will generate this file automatically for us.
Setting Up the Database
If you’re an experienced Database administrator, please skip this section. If you know nothing about MySQL, or if you—like me—just learned enough to get through that one homework assignment, please read on.
Databases can be tricky beasts. I set up my first MySQL database in the command line because I’m stubborn like that, but I highly recommend you use a GUI to interact with your database. Most webhosts have phpMyAdmin installed, so that’s what we’ll use.
You can install phpMyAdmin from the terminal with:
sudo apt-get install phpmyadmin php-mcrypt php-mbstring php-gettext
During the installation process you will be prompted to take a few actions.
- select “apache2” for your server
- Warning At the first prompt, apache2 will be highlighted but not selected. You need to select apache2 for the server by hitting space, tab, then enter
- select “yes” to use
- enter your root password from when you installed MySQL
- enter a new username and password for the phpMyAdmin application
Once phpMyAdmin is installed, you’ll need to enable two extensions for PHP with:
sudo phpenmod mcrypt sudo phpenmod mbstring
To ensure Apache is serving phpMyAdmin correctly, we’ll need to restart it again with:
sudo service apache2 restart
Now you should be able to log in to phpMyAdmin by going to
localhost/phpmyadmin in a web browser. You can log in using the username “root” and the password you selected earlier.
Leave this tab open. We’re coming back to it.
Almost all WordPress hosts have phpMyAdmin installed, and you should find directions to log in to your domain’s account on your web host account page. Once you’ve logged into your phpMyAdmin account, you can export your database.
On the left side of the phpMyAdmin panel, you’ll see a list of all the databases on your server.
Select the one matching the site you’re trying to clone. Normally it will have your domain name in the title for easy recognition.
With the database selected, click the “Export” button along the top of the browser window.
Choose “Quick” for Export Method and SQL for format. When you click Go, you’ll start downloading a .SQL file.
Mosey on back to your
localhost/phpmyadmin browser tab, and import the .SQL file you just downloaded. This will create a new database containing the same contents as your live website.
There are a couple lines you’ll have to change. Enter the SQL tab on your localhost's phpMyAdmin, and type the following:
UPDATE wp_options SET option_value = replace(option_value, 'http://www.example.com', 'http://localhost/[your project's name]') WHERE option_name = 'home' OR option_name = 'siteurl'; UPDATE wp_posts SET post_content = replace(post_content, 'http://www.example.com', 'http://localhost/[your project's name]'); UPDATE wp_postmeta SET meta_value = replace(meta_value,'http://www.example.com','http://localhost/[your project's name]');
Of course, replace
http://www.example.com with your website’s domain. If you have trouble here, you can always manually edit these tables using the phpMyAdmin GUI.
Be extra careful with details here. Note the lack of a trailing slash after your project, and
http:// preceding localhost. Press “Go” to commit the change.
Start Your Local WordPress Site
If your WordPress files still haven’t downloaded, go grab a lemonade or something. Hydration is important, and you’ve earned a treat.
Once you’re hydrated and your files have downloaded, go to
localhost/[you project's name]/wp-admin or your custom admin URL if you use one. You should be able to log in with the same username and password you use on your live site.
After you log into your admin site, you’re done! You now have a working clone of your live WordPress site. You can customize themes, edit plugins, and do whatever you want in a safely isolated environment without fear of breaking anything.
If you run into any problems with these instructions, please let me know and I’ll try to point you in the right direction.