Consolidating setup of local Dev environment documentation and testing instructions.

[paaljoachim]

There are several places that have the same kind of documentation for setting up a local dev environment. These exist in various degrees of completeness and quality. There is also a crossover of docs in regards to testing/contributing. It would be great to see if we can combine these efforts and create one central place for documentation for setting up a local dev environment + testing instructions.

Here is an example from the Block Editor Handbook:
​https://developer.wordpress.org/block-editor/tutorials/devenv/#quick-start
+
Issue in relation to testing pull requests:
​https://github.com/WordPress/gutenberg/issues/25202

Here is an example from a post on P2:
​https://make.wordpress.org/core/2021/01/15/test-scrub-for-wordpress-5-7/

Core Handbook Getting Started
​https://make.wordpress.org/core/handbook/tutorials/getting-started/#setting-up-a-local-server

​https://github.com/WordPress/wordpress-develop

---

Documentation we can easily update showing methods for WordPress core and Gutenberg. A document for setting up a local dev environment, and a document for testing trac tickets as well as Gutenberg Github pull requests.

Having an easy to follow step by step hand holding method with some short explanations and some troubleshooting tips would be a huge help to people at various skill levels. Making it easy for developers and non developers to follow.

[paaljoachim]

To begin the road to consolidating a setup for core and Gutenberg I need to know how both are done. By writing the instructions for both in this ticket.

The following are instructions for setting up a Local WP dev environment as well as how to test Trac tickets and Github PR's.

---

Core instructions. Setting up a Local Dev Environment.

I have with help from @hellofromtonya updated the testing instructions for setting up a local WP dev environment + testing trac tickets.

Setting up a local Development Environment for WordPress core.
The following are the Mac and Linux instructions. Further below are Window instructions.

1: Open Terminal.
2: Install homebrew by pasting

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

You might be asked if you want to install the Xcode Command Line Tools. Confirm yes.

3: Install Git by typing: brew install git
4: Install Docker by downloading the app here:
​https://www.docker.com/products/docker-desktop
Or in terminal install Docker by typing:

brew cask install docker

If that does not work type:

brew install cask docker

5: In terminal. Install Node by typing:

brew install node

6: Open the Docker app on your computer and ignore the welcome screen that tells you to create a container. (NB! If you happen to have MAMP, VVV or anything else like that running. It might create a problem to get Docker running correctly. It is advised to closing these other programs.)

7: Clone the Github repository. Go to ​https://github.com/WordPress/wordpress-develop
Click the green button (Code) at the top of the repository. Copy the HTTPS URL. ​https://github.com/WordPress/wordpress-develop.git
In terminal type:

git clone https://github.com/WordPress/wordpress-develop.git

8: Go to the directory where you cloned the repo.
Type:

cd wordpress-develop

9: Now type these 4 commands.

9A.

npm install

9B.

npm run build:dev

9C.

npm run env:start

If you have problems running the above command then use

brew install subversion

9D.

npm run env:install

10: You should now be able to access the development version of WordPress at ​http://localhost:8889/.
Login with using
username: admin
password: password
-
-
A video tutorial I made for showing how to setup a local WP dev environment for WordPress core.
​https://youtu.be/iit57Sg2pkU

---

Testing a Trac ticket or a Github PR.

NB!
There are special testing instructions for testing the themes 2019, 2020 or 2021. See instructions further below.

Open terminal and go to

cd wordpress-develop

An example Trac ticket:
​https://core.trac.wordpress.org/ticket/43890

Type:

npm run grunt patch:43890

Add the trac ticket number to be tested.
After inserting the command an option will show up to where one can select which patch to test. With the up and down arrows on your keyboard select the newest patch (diff).

Login to your local WordPress site: ​http://localhost:8889/ with
username: admin
password: password

Check the results of the patch.

Sometimes one might be asked to test a WordPress Develop Github PR.
Here is an example of what to type in terminal (change the pull number):

npm run grunt patch:https://github.com/WordPress/wordpress-develop/pull/957

Login to ​http://localhost:8889/ and see if the patch/Pull Request (PR) works.

When done testing, discard the patch/PR's code changes to restore the wordpress develop directory by typing:

git reset --hard

-
-
-

Testing the following themes: 2019, 2020 and 2021.

These themes have their own build process which needs to be run before core development is run.

Here is an example for testing the Twenty Twenty One theme.

1. First go to (if you are not already in the directory.):

cd wordpress-develop

Add:

cd src/wp-content/themes/twentytwentyone

Example.

paaljoachimromdahl@Paals-MacBook-Pro wordpress-develop % cd src/wp-content/themes/twentytwentyone
paaljoachimromdahl@Paals-MacBook-Pro twentytwentyone %

2. Inside the twentytwentyone directory.

2A. Type:

npm install

2B. Type:

npm run build

We now have run the build for the Twenty Twenty One theme. The theme needs to have the Sass styles compiled before running the wordpress-develop build.

3. Go back to the wordpress-develop directory.

Type:

cd ~/wordpress-develop

4. Inside wordpress-develop.

Type:

npm run build

Go back to the "Testing a Trac ticket or a Github PR." further above.

-
-
A video tutorial I made for showing how to test a trac ticket patch:
​https://youtu.be/87lvITWERTs
-
-

Troubleshooting in relation to testing.

Close and reopen terminal. Test again.
When you open ​http://localhost:8889/ be sure to log out and do a hard refresh and then log back in again.

Patches that includes JavaScript (JS) files one will also need to run the following command after having applied the patch:

npm run build

or

npm run build:dev

It will update the development build. Hopefully the patch will now be testable.
If the JavaScript is still not working then run the command.

npm run dev

Log out of the dev site and do a hard refresh and log back in again.

Something might happen so that you need to apply the patch again. If you have some errors then reseting the testing environment might help. Use the command:

git reset --hard

If your not able to open ​http://localhost:8889/
Then you might need to start up the environment by typing:

npm run env:start

-
-

Uninstall instructions

1: Uninstall Homebrew.
In terminal type:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall.sh)"

Type y to confirm.
Type your password.

2A.
Uninstall Docker.
Open Docker and go to the Dashboard.
Click the bug icon button seen in the top blue bar.
Click the Uninstall button.
Then drag the Docker app to your trash can.

2B.
Skip uninstalling Docker.
(If you do not want to remove Docker. Then follow these steps.)
Uninstall WordPress developer environment
In terminal type:

npm run env:reset

This will uninstall the Docker image and all the virtual discs it creates.

3: Delete wordpress-develop
Open the user folder in the root the wordpress-develop folder is located. Select it and drag it to the trash can.

Resource:
​https://github.com/Homebrew/install

---

Windows instructions

Replace the above Mac/Linux instructions 1 - 6 with the following:

1: Install Git from ​https://git-scm.com/download/win
2: Download Docker Desktop from: ​https://www.docker.com/products/docker-desktop
Click Ok to enable Hyper-V and the Container features. Follow the prompts.
3: Download and install Node.js and NPM LTS version from ​https://nodejs.org/en/ (they are bundled together in one installer)

4: Restart your computer after completing step 3 to ensure system settings are correctly applied.

Follow steps 7 and onward in the Mac/Linux instructions.

Uninstall Windows Instructions

1: Uninstall Docker
Go to the "Uninstall Program" screen and select to uninstall Docker.

2: Delete wordpress-develop
Locate the wordpress-develop folder and delete.

Resource: ​https://docs.docker.com/docker-for-windows/install/

NB! I plan on creating a Learn Lesson/Workshop.

[Clorith]

In the case of a Windows install, you would replace steps 1 through 6 with the following:

1: Install Git from ​https://git-scm.com/download/win
2: Download Docker Desktop from ​https://www.docker.com/get-started
3: Download and install Node.js and NPM from ​https://nodejs.org/en/ (they are bundled together in one installer)

4: Restart your computer after completing step 3 to ensure system settings are correctly applied.

Docker automatically starts with your machine once installed on Windows unless you configure it to do otherwise.

Removing them afterwards should be a familiar experience to Windows users, as you would visit your computers "uninstall programs" screen and just select them there and they will be gone.

[paaljoachim]

Setting up a local WP development Environment using VVV - Vagrant.

Some links.
​https://make.wordpress.org/core/handbook/tutorials/installing-a-local-server/installing-vvv/

​https://github.com/WordPress/contributor-day-handbook/blob/master/*Start%20Here%20-%20General%20Guides/How%20to%20setup%20VVV.md

​https://github.com/Varying-Vagrant-Vagrants/CD-USB-Generator

​https://varyingvagrantvagrants.org/docs/en-US/slack/

---

@abhanonstopnewsuk @macgraphic @tom

Step by steps tutorial will be added in this comment.
I will do research and figure out the newest instructions for Mac and Windows and add them here. Then add instructions + video to Learn.

---

I have been following this tutorial:
How to Set Up VVV for Contributing to WordPress.
​https://github.com/WordPress/contributor-day-handbook/blob/master/*Start%20Here%20-%20General%20Guides/How%20to%20setup%20VVV.md

Here are some shorter instructions.

VVV (Varying Vagrant Vagrants) is a virtual machine that runs on Virtualbox. In other words, it is a self-contained local development environment aimed at WordPress developers. It can be used to build sites and contribute to the development of WordPress Core.

Mac, Linux and Windows instructions.

1- Installing VVV

Install VirtualBox: ​https://www.virtualbox.org/wiki/Downloads
Install Vagrant: ​https://www.vagrantup.com/downloads
Reboot your computer.

VVV Installation instructions: ​https://varyingvagrantvagrants.org/docs/en-US/installation/

Quick start instructions for installing VVV.
Cloning the main VVV repo into a local directory. In terminal, add:

git clone -b stable git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vagrant-local

The VVV repo will now be added to the new directory vagrant-local. Located in your operating system user root folder.

2- Start up VVV

Restart terminal then add

cd vagrant-local

Install local vagrant plugins if you have not already done so, add:

vagrant plugin install —-local

Start the Vagrant environment add this command:

vagrant up

You might need to add your operating system administrator password to properly modify the hosts file on your local machine. (When the prompt is seen type your password and click the enter/return key.)

Visit the VVV dashboard at ​http://vvv.test in your browser. You should see a listing of all the sites VVV created, as well as links to other administration-related tools.

VVV also includes the following two (disabled) environments.
-​http://trunk.wordpress.test/ An SVN-based WordPress core trunk setup, useful for Contributor Days, Trac tickets, patches, general core contributing, etc.
-​http://wp-meta.test A collection of sites for contributing to WordPress.org.

To enable wordpress-trunk (and wordpress-meta-environment).
To enable these environments, check if you have a config/config.yml file in your vagrant-local folder. If you do not have a config.yml file, then run vagrant status and it will be created for you.
In config.yml, look for the wordpress-trunk (and wordpress-meta-environment) and change skip_provisioning: true to skip_provisioning: false and save.

Back in terminal, add:

vagrant up --provision

to apply the change.

This will take some time to run, especially if you have enabled the Meta environment.

Go back to: ​http://vvv.test/
Notice the wordpress-trunk and wordpress-meta-environment are now active along with one.wordpress.test and two.wordpress.test.

Go to ​http://trunk.wordpress.test/ and login at
​http://trunk.wordpress.test/wp-login.php
using these credentials:
admin
password

In terminal.
Add (if you are in the vagrant-local directory then skip to the next step):

cd vagrant-local

This opens the vagrant-local directory/folder inside the user root folder.

Add:

vagrant ssh

A pixelated waving bear will be seen.

Add:

cd /srv/www/wordpress-trunk/public_html

This enters the public_html folder inside wordpress-trunk which is inside the www folder. We need to use wordpress-trunk to test Trac patches and Github PRs.

Find a trac ticket with a patch.

I tried this one: ​https://core.trac.wordpress.org/ticket/39004
Used this command:

npm run grunt patch:39004

Uninstall

Uninstalling VVV VM (Virtual Machine)
In terminal go to the vagrant folder. Add:

cd vagrant-local

Then add:

vagrant destroy

Follow the prompts.

Delete the vagrant-local folder inside the OS root user folder.

Uninstalling Vagrant

Windows: Uninstall using the add/remove programs section of the control panel.
Mac: In terminal add:

sudo rm -rf /opt/vagrant /usr/local/bin/vagrant

Insert your OS password.

Then add:

sudo pkgutil --forget com.vagrant.vagrant

Linux: In terminal add:

rm -rf /opt/vagrant

then add:

rm -f /usr/bin/vagrant

Uninstalling VirtualBox

Windows: Go to Add/Remove Programs. Uninstall Virtualbox.
Linux: In terminal add:

sudo apt-get purge virtualbox*

I also saw this in the user manual:
Uninstallation of Oracle VM VirtualBox on Oracle Solaris requires root permissions. To perform the uninstallation, start a root terminal session and run the following command:

pkgrm SUNWvbox

After confirmation, this will remove Oracle VM VirtualBox from your system.

Mac:
Download the installer: ​https://www.virtualbox.org/ and mount.
Double click the VirtualBox_Uninstall.tool (One needs to go to Preferences -> Security & Privacy -> General and accept to open the tool.)
Follow the prompts.
Uninstall also FUSE????
When it is done it will say: [Process completed]

Resources:
​https://www.vagrantup.com/docs/installation/uninstallation

​https://technical-tips.com/blog/software/virtualbox-uninstall-completely--how-21709
​https://osxdaily.com/2019/01/25/uninstall-virtualbox-mac-completely/
VirtualBox manual.

---

NB!
I have an update 25th of May to the vagrant / VVV tutorial in a Google Doc form:
​https://docs.google.com/document/d/1v48dsBdxqpoqFUh_lrN_4gEq5HtRlfIC3ImjZYeRy9s/edit#

[paaljoachim]

I went ahead and made a Gutenberg issue.
wp-env: Consolidating setup of the dev environment for Core and Gutenberg.
​https://github.com/WordPress/gutenberg/issues/29448

I believe we need some adventurers to explore the way forward.

[mai21]

On Ubuntu, At step 9c, I got this:

npm run env:start

> WordPress@5.8.0 env:start /home/mai/wordpress-develop
> node ./tools/local-env/scripts/start.js

Traceback (most recent call last):
  File "urllib3/connectionpool.py", line 677, in urlopen
  File "urllib3/connectionpool.py", line 392, in _make_request
  File "http/client.py", line 1277, in request
  File "http/client.py", line 1323, in _send_request
  File "http/client.py", line 1272, in endheaders
  File "http/client.py", line 1032, in _send_output
  File "http/client.py", line 972, in send
  File "docker/transport/unixconn.py", line 43, in connect
PermissionError: [Errno 13] Permission denied

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "requests/adapters.py", line 449, in send
  File "urllib3/connectionpool.py", line 727, in urlopen
  File "urllib3/util/retry.py", line 410, in increment
  File "urllib3/packages/six.py", line 734, in reraise
  File "urllib3/connectionpool.py", line 677, in urlopen
  File "urllib3/connectionpool.py", line 392, in _make_request
  File "http/client.py", line 1277, in request
  File "http/client.py", line 1323, in _send_request
  File "http/client.py", line 1272, in endheaders
  File "http/client.py", line 1032, in _send_output
  File "http/client.py", line 972, in send
  File "docker/transport/unixconn.py", line 43, in connect
urllib3.exceptions.ProtocolError: ('Connection aborted.', PermissionError(13, 'Permission denied'))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "docker/api/client.py", line 214, in _retrieve_server_version
  File "docker/api/daemon.py", line 181, in version
  File "docker/utils/decorators.py", line 46, in inner
  File "docker/api/client.py", line 237, in _get
  File "requests/sessions.py", line 543, in get
  File "requests/sessions.py", line 530, in request
  File "requests/sessions.py", line 643, in send
  File "requests/adapters.py", line 498, in send
requests.exceptions.ConnectionError: ('Connection aborted.', PermissionError(13, 'Permission denied'))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "docker-compose", line 3, in <module>
  File "compose/cli/main.py", line 81, in main
  File "compose/cli/main.py", line 200, in perform_command
  File "compose/cli/command.py", line 70, in project_from_options
  File "compose/cli/command.py", line 153, in get_project
  File "compose/cli/docker_client.py", line 43, in get_client
  File "compose/cli/docker_client.py", line 170, in docker_client
  File "docker/api/client.py", line 197, in __init__
  File "docker/api/client.py", line 222, in _retrieve_server_version
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', PermissionError(13, 'Permission denied'))
[27279] Failed to execute script docker-compose
child_process.js:655
    throw err;
    ^

Error: Command failed: docker-compose up -d wordpress-develop
    at checkExecSyncError (child_process.js:616:11)
    at execSync (child_process.js:652:15)
    at Object.<anonymous> (/home/mai/wordpress-develop/tools/local-env/scripts/start.js:8:1)
    at Module._compile (internal/modules/cjs/loader.js:1063:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:769:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
    at internal/main/run_main_module.js:17:47 {
  status: 255,
  signal: null,
  output: [ null, null, null ],
  pid: 27277,
  stdout: null,
  stderr: null
}
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! WordPress@5.8.0 env:start: `node ./tools/local-env/scripts/start.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the WordPress@5.8.0 env:start script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

Then install docker-compose as per ​https://docs.docker.com/compose/install/ then running the same cmd with sudo works.

Currently stuck in another error with step 9D

sudo npm run env:install

> WordPress@5.8.0 env:install /home/mai/wordpress-develop
> node ./tools/local-env/scripts/install.js

Creating wordpress-develop_cli_run ... done

Warning: file_put_contents(/var/www/src/wp-config.php): failed to open stream: Permission denied in phar:///usr/local/bin/wp/vendor/wp-cli/config-command/src/Config_Command.php on line 164
Error: Could not create new 'wp-config.php' file.
ERROR: 1
child_process.js:655
    throw err;
    ^

Error: Command failed: docker-compose run --rm cli config create --dbname=wordpress_develop --dbuser=root --dbpass=password --dbhost=mysql --path=/var/www/src --force
    at checkExecSyncError (child_process.js:616:11)
    at execSync (child_process.js:652:15)
    at wp_cli (/home/mai/wordpress-develop/tools/local-env/scripts/install.js:48:2)
    at Object.<anonymous> (/home/mai/wordpress-develop/tools/local-env/scripts/install.js:10:1)
    at Module._compile (internal/modules/cjs/loader.js:1063:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:769:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
    at internal/main/run_main_module.js:17:47 {
  status: 1,
  signal: null,
  output: [ null, null, null ],
  pid: 29921,
  stdout: null,
  stderr: null
}
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! WordPress@5.8.0 env:install: `node ./tools/local-env/scripts/install.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the WordPress@5.8.0 env:install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

[caseymilne]

Is there any problem with mentioning some of widely used freemium local environment setups for Windows? Personally I use Desktop Server, it's available for free and it's a 1-click install. Another installable option is Local by Flywheel. XAMPP is another Windows environment option for a simulated LAMP server, it is truly free with no limitations. But the setup is more prone to complications than using Desktop Server which is layered over top of it.

Generally I think while much of the audience might be comfortable with command line approaches, if we include approach that don't require command line we broaden the audience. Those 2 in particular, Desktop Server and Local by Flywheel have managed to overcome some of the very frustrating environment config issues that can happen on Windows.

I think the format for a good Windows guide to local environment would start off with an intro about the variety of options. Perhaps stating if you're comfortable with a CLI approach we recommend Docker. If you want the fastest easier approach choose one of the recommended software options Desktop Server or Local by Flywheel. Then branch off the docs to cover each option separately.

[paaljoachim]

Hi @mai21

Did you figure out how to fix the error in Ubuntu? I believe you could ask directly in the Slack core channel or on ​https://wordpress.stackexchange.com/ or even in a forum here: ​https://wordpress.org/support/

If you did figure out a approach, then please readjust your comment to also include the solution. Thanks!

---

Hey @caseymilne

Is there any problem with mentioning some of widely used freemium local environment setups
for Windows?

No problem there. I just have not been able to create tutorials for Desktop Server and Local yet. I could use some help with that.

I think the format for a good Windows guide to local environment would start off with an
intro about the variety of options. Perhaps stating if you're comfortable with a CLI
approach we recommend Docker. If you want the fastest easier approach choose one of the
recommended software options Desktop Server or Local by Flywheel. Then branch off the docs
to cover each option separately.

This sounds like a very good approach!
Perhaps you could create a Google doc to where we can share additional ideas?
Thank you for sharing, Casey!

[circlecube]

I agree with this idea. The docs seem to have many suggestions on what to use to set up a local dev environment and much is dated. Having a central place to this would help keep it updated and clear for new folks.

Another distinction would be good to make is detailing a local dev environment for building sites and for core development. As I think some tools shine better in one circumstance vs others. Those are two different use cases though and if we're going to have a centralized place to cover local dev, a run down covering both situations would be ideal.

Also @paaljoachim, another place to feature the video content would be learn.wp.org!

[paaljoachim]

Hey @circlecube

I have these two lessons that have been in draft form in Learn for the last few months:
Setting up a local WordPress Development Environment for core
​https://learn.wordpress.org/?p=4248&post_type=wporg_workshop&preview=1&_ppp=7b223d4355
and
Testing a Trac ticket or a Github PR.
​https://learn.wordpress.org/?p=3872&post_type=wporg_workshop&preview=1&_ppp=a8a96ae1ab
(I do not know how long the public preview links might be available.)
If you can test these out and give feedback in the Slack #training channel then that would be helpful.