This will set you up for VersionPress development. 👩💻 👨💻
Our approach is:
- You develop in local tools you're comfortable with – PhpStorm, vim, VSCode, ...
- Runtime is handled by Docker. You don't need MAMP / XAMPP, local installation of Selenium, etc.
- Common tasks are automated via npm scripts, for example,
npm run build.
This software is expected on your machine:
- Git 2.10+
- Node.js 8+, npm 6+
- Docker 18.03+
- PHP 7+ and Composer 1.4+
Windows users: use Git Bash¶
Git Bash (part of Git for Windows) is required on Windows, please use it instead of
cmd.exe / PowerShell for both interactive sessions and as your npm script shell:
npm config set script-shell "c:\Program Files\git\bin\bash.exe"
See also Windows tips below.
git clone https://github.com/versionpress/versionpress
Have a ☕, this will take a while.
Tip: From time to time, it's useful to clean up everything and pull latest Docker images. Run
npm run refresh-dev.
Dockerized development environment¶
To start a development site:
- Make sure Docker is running and ports 80 and 3306 are free (no local MAMP / XAMPP / MySQL running).
This will start a set of Docker containers in the background. When everything boots up, log into the test site at http://localhost, install WordPress and activate VersionPress on the Plugins page. You're now all set up! 🎉
Let's explore your development environment:
- VersionPress source files are directly mapped to the site's
wp-content/plugins/versionpress. Any changes you make locally are immediately live.
- Database can be inspected using Adminer at http://localhost:8099, server name
r00tpwd. You can also use tools like MySQL Workbench or
mysqlcommand-line client, e.g.,
mysql -u root -p.
- WordPress root is mapped to
./dev-env/wp. You can use your local Git client to inspect the site's history there.
- To invoke WP-CLI or Git commands in the site, create a terminal session via
docker-compose exec wordpress /bin/bashor invoke the command directly, e.g.,
docker-compose exec wordpress git logor
docker-compose exec wordpress wp option update blogname "Hello".
Some useful tips for managing your Docker environment:
docker-compose pslists running containers
docker-compose logs -fdisplays live logs
docker-compose logs wordpressdisplays logs of a single service
docker statsshow live CPU / memory usage
dcwill save you some typing.
- Values in
docker-compose.ymlcan be customized via
npm stop to stop the development environment. Run
npm run stop-and-cleanup to also clean up WordPress files and MySQL database for a fresh start next time.
VersionPress consists of PHP code implementing the core versioning logic and a React frontend. This section is about the former, the latter is described in Frontend development below.
For PHP development, we recommend PhpStorm and ship project files for it. The steps here have been tested in PhpStorm 2018.1.
npm run init-phpstorm. This copies
plugins/versionpress project in PhpStorm. On the first start, you'll see two prompts:
Enable WordPress support but leave the installation path empty (ignore the warning):
Enable Composer sync.
For Code Sniffer inspections to work, there's a one-time configuration: Go to Settings > Languages & Frameworks > PHP > Code Sniffer, select Local, click the three dots next to it and provide your full system path to
Note: Most VersionPress code uses the PSR-2 coding standard with only the parts directly interacting with WordPress using WordPress conventions. For example, global functions are defined as
It is also useful to install the EditorConfig extension, VersionPress ships with some basic formatting rules.
Please refer to the Contributing code section in
Start the Docker stack with
In PhpStorm, go to Settings > Languages & Frameworks > PHP > Servers and check the path mappings of the pre-configured VersionPress-dev server. Specifically, update the WordPress mapping which PhpStorm does not persist automatically:
The two mappings should be:
<your local path>/plugins/versionpress->
<your local path>/ext-libs/wordpress->
The default zero configuration settings in Settings > Languages & Frameworks > PHP > Debug should be fine:
Enable debugging in the browser, most commonly using a browser extension or a bookmarklet:
Place a breakpoint somewhere, e.g., in the main
versionpress.php file, and start listening for debug connections in PhpStorm.
Reload a page in your browser. Debugging should now work:
After you're done with debugging, run
npm stop or
npm run stop-and-cleanup.
PhpStorm / WebStorm setup¶
npm run init-phpstormif you haven't done that already.
- Open the
frontendproject in PhpStorm.
Linting task is set up for the frontend project. Run
npm run lint in the
Running frontend separately¶
For pure frontend development, it's more convenient to run it outside of the WordPress administration. Let's assume you run the frontend against the default Docker site.
- Make sure that the site is running and that VersionPress is activated in it. You should be able to visit
http://localhostin the browser and the
frontend/src/config/config.local.tsshould contain this URL as API root.
In your test WordPress site, put this to
wp-config.php(the file should be editable at
npm startin the
Source code edits will be automatically reflected in the browser.
npm run build, it will produce a file like
The version number is based on the nearest Git tag and can also be something like
3.0.2-27-g0e1ce7f meaning that the closest tag is
3.0.2, there have been 27 commits since then and the package was built from
git describe --tags for more examples.
As noted in Getting started, we only support Git Bash on Windows, a shell that comes with Git for Windows.
cmd.exe or PowerShell will not work as we use Linux-style syntax (single quotes, setting environment variables, etc.) and tools like
rm -rf in scripts.
Git Bash is generally an awesome shell, the only problems you might encounter are related to paths. For example, Docker messes with them and when you try to run
docker run --rm -it ubuntu /bin/bash, you'll see an error like
C:/Program Files/Git/usr/bin/bash.exe: no such file or directory. Docker prepends
C:/Program Files/Git for some reason but you can use this workaround or use double slash like
Docker Desktop vs. Docker Toolbox¶
If you can, use Docker Desktop, not Docker Toolbox. The experience will be smoother (for example, ports are forwarded by default) and also the performance is much better due to a more modern virtualization technology.
Performance is important
You'll notice a big difference between Docker Desktop and Docker Toolbox, for example, tests run 3-4× slower in Toolbox (10 vs. 40 minutes). You might also run into various timeouts, for example,
wp_remote_get() has a default timeout of 5 seconds which might not be enough.
Note that it's generally hard to improve the performance of Toolbox, even if you give the virtual machine more CPUs and RAM, see these results for tests.
If you need to use Docker Toolbox because you have an older machine or OS, brace yourself and follow these steps:
- Enable port forwarding in VirtualBox for ports 80, 3306 and 8099.
- If you have the repo checked out in a folder not under
C:\Users\youruser, add it as a shared folder in VirtualBox settings. For example, add a share where Folder Path is
C:\Projects, Folder Name is
c/Projects, check both "Auto-mount" and "Make Permanent" and restart the VM. Details.
- Feel free to use the default Docker Quickstart Terminal: it uses Git Bash which is good.
Disable antivirus software¶
You might want to disable your antivirus software when working with Docker. Recommendations differ between version, please look it up.
Developing the dev setup¶
Meta! If you're working on updating the dev setup (this document, Docker images, etc.), here are some tips for you.
Simpler tasks are scripted directly in
package.json, more complex ones in the
./scripts folder. See its README for more info.
Building and pushing images¶
The only goal of our images is to be close to the official project and have the right environment in it, e.g., the PHP version. We don't care that much about specific WordPress versions (WordPress is often installed dynamically anyway, based on
test-config.yml) so we only use "vague" tags like
To build and push tags to Docker Hub:
npm run build-images
npm run push-images
You can get Docker Hub digests by running:
$ npm run get-image-digests cli sha256:11c49ba4d7198c17660f30e8db4d00ca356b1c4414f338076bf99ab4dd295184 php7.2-apache sha256:39ed34f84a5ccf8ab47eb1db4041c226ffe6f874127ead4c26f0b607457b7377
Links to older documents¶
Legacy approach is documented at the