How to set up a WordPress site locally

Why I make this?

Someone sent me a WordPress site in a zip file. I had to figure out how to make it run on my local machine (in an Ubuntu virtual machine, to be exact). I tried some of these GUI softwares but couldn’t make them work. So I went the old school dirty way – bash commands.

How to do this?

What I received:

1. A zip file containing a WordPress site.
2. A .sql database file.

I figured that the .sql file is the WordPress database.

How to get shit running:

1. Set up an Ubuntu virtual machine. Why virtual machine? So you get a contained sandbox and a clean slate for your experiments. Why Ubuntu? It’s just a whole lot easier to do these things on Linux. Screw your MAMP and WAMP stacks.

2. Install nginx, mysql-server and php7.4. That’s your LEMP stack right there.¹ DigitalOcean tutorials can help you set these things up. Use php7.4 because most of the Internet breaks on php8.1. You’ll need to add a new ppa package for that - DigitalOcean can tell you how. All the additional php packages that you install should also have the php7.4 prefix in front of them. If you install php-fpm you might just get php8.1-fpm. So install php7.4-fpm instead.

3. Read the wp-config.php file in your site folder to get the database name and user credentials.

4. Create a new database in mysql with that name. Then add a user with that password to that database. Then grant access to that user over that database. Again, DigitalOcean has your back.

5. Now open mysql as this user (mysql -u USER -p), open the database (USE DATABASENAME;), and then import the .sql file using: source /path/to/database.sql. Wait while it imports everything. You can check if it worked by running SHOW TABLES; and seeing if it lists all the tables in the database. If shit breaks, you are on your own - go figure.

6. At this point your database is ready. Now you just have to copy your site over and tell Nginx to start redirecting localhost traffic to it.

7. Assuming you have copied your site to /var/www/wordpress/, follow DigitalOcean’s instructions to create a site config in the /etc/nginx/sites-available/ directory. You can get the complete server config in this DigitalOcean tutorial. Make sure that the php-fpm version is set correctly in the server config. Also make sure that you have pointed the root in the right direction (which is /var/www/wordpress in this case).

8. Finish things off by creating a symlink (ln -s) to the sites-enabled directory, running nginx -t and restarting nginx (systemctl restart nginx). Note: you might have a ‘default’ config in the sites-enabled directory. You can delete that. Otherwise your localhost on port 80 (default port) will point to that. You want it to point to your WordPress site instead. Or you could change your WordPress config to listen to traffic on port 81 or whatever. Up to you.

9. Now you should be able to access your WordPress site on localhost. If it doesn’t load, something is wrong with your nginx config. Go back to step 7. If it loads and the site runs as intended, congratulations. Go to /wp-admin/ and have your fun.

If it doesn’t, well here we go, lad.

1. Enable debugging in your config file. Add the following lines to your wp-config.php file:

1
2

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

2. Now try to access your site again. If it breaks, you should probably see it in the browser. Or see the debug.log file in your site’s root directory. Open it and see what’s wrong.

3. Most likely it’s a theme or plugins that are broken. Simply rename the plugins folder to plugins.hold (sudo mv /var/www/wordpress/wp-content/plugins /var/www/wordpress/wp-content/plugins.hold). Now try to access the site again. If it works, great, go to your admin dashboard and see if there are updates to plugins available and then activate them one by one and hope they work.

4. If when you try to update plugins, WordPress says it needs FTP access to your server or something, simply add this line to your wp-config.php file: define('FS_METHOD', 'direct');. This will allow WordPress to update plugins directly without needing FTP access. You’ll also need to give the www-data user ownership of the site directory:

1
2
3

sudo chown -R www-data:www-data /var/www/wordpress
sudo find /var/www/wordpress -type d -exec chmod 755 {} \;
sudo find /var/www/wordpress -type f -exec chmod 644 {} \;

5. If plugins aren’t it, then it’s probably a theme. Try disabling the themes one by one. Or disable all themes except the WordPress default theme (usually called twentytwentythree or something like that). You’ll also have to change the theme option for your site in the database. You can do that by running the following command in mysql (make sure you are in the right database):

1
2

UPDATE wp_options SET option_value = 'twentytwentythree' WHERE option_name = 'template';
UPDATE wp_options SET option_value = 'twentytwentythree' WHERE option_name = 'stylesheet';

If you get an error saying wp_options does not exist, then it’s probably because the database prefix in your config file is set to something else. Let’s say the prefix is “bowow” so your table will then be called bowow_options. Change the SQL commands accordingly.

6. Now go to localhost in the browser and it should most likely work. Then figure out how to get the broken theme(s) to work from there.

7. One more thing, the default site URL may be set to something else. You’ll need to change that to http://localhost as well. You can do that by running the following command in mysql (make sure you are in the right database and use the right table name):

1
2

UPDATE wp_options SET option_value = 'http://localhost' WHERE option_name = 'siteurl';
UPDATE wp_options SET option_value = 'http://localhost' WHERE option_name = 'home';

8. Lastly, if you can’t log into /wp-admin because you don’t know what user credentials to use, you can create a new user or just find the existing admin user and change its password. To do that, first generate an MD5 hash for your new password (this tool can help). Then go into mysql one more time, find the user name in the wp_users table and modify its password:

1
2

SELECT * FROM wp_users; // find the user_login corresponding to the admin user
UPDATE wp_users SET user_pass = 'THE_MD5_HASH_YOU_JUST_CREATED' WHERE user_login = 'WHATEVER_THE_ADMIN_USERNAME_IS';

Now you can go to /wp-admin and log in with the new password for the admin user.

If it still doesn’t work – think about why you are in the position where you are sent WordPress sites in a zip file. Then think about how you can get out of that position. Now, go do that.