wp-site v0.0.1

This project replaces all wp-env and WP_ENV_* references with wp-site and WP_SITE_ respectively, including config files. It is an exact copy of the @wordpress/wp-env project. The only difference is that it builds a custom Docker image (lib/docker/Dockerfile) rather than using the standard WordPress one. And its a convenient name for a CLI command ;)

wp-site

wp-site lets you easily set up a local WordPress environment for building and testing plugins and themes. It's simple to install and requires no configuration.

Quick (tl;dr) instructions

Ensure that Docker is running, then:

$ cd /path/to/a/wordpress/plugin
$ npm -g i wp-site
$ wp-site start

The local environment will be available at http://localhost:8888 (Username: admin, Password: password).

Prerequisites

wp-site requires Docker to be installed. There are instructions available for installing Docker on Windows 10 Pro, all other versions of Windows, macOS, and Linux.

Node.js and NPM are required. The latest LTS version of Node.js is used to develop wp-site and is recommended.

Installation

Installation as a global package

After confirming that the prerequisites are installed, you can install wp-site globally like so:

$ npm -g i wp-site

You're now ready to use wp-site!

Installation as a local package

If your project already has a package.json, it's also possible to use wp-site as a local package. First install wp-site locally as a dev dependency:

$ npm i wp-site --save-dev

Then modify your package.json and add an extra command to npm scripts (https://docs.npmjs.com/misc/scripts):

"scripts": {
	"wp-site": "wp-site"
}

When installing wp-site in this way, all wp-site commands detailed in these docs must be prefixed with npm run, for example:

# You must add another dash to pass the "update" flag to wp-site
$ npm run wp-site start -- --update

instead of:

$ wp-site start --update

Usage

Starting the environment

First, ensure that Docker is running. You can do this by clicking on the Docker icon in the system tray or menu bar.

Then, change to a directory that contains a WordPress plugin or theme:

$ cd ~/gutenberg

Then, start the local environment:

$ wp-site start

Finally, navigate to http://localhost:8888 in your web browser to see WordPress running with the local WordPress plugin or theme running and activated. Default login credentials are username: admin password: password.

Stopping the environment

To stop the local environment:

$ wp-site stop

Troubleshooting common problems

Many common problems can be fixed by running through the following troubleshooting steps in order:

1. Check that wp-site is running

First, check that wp-site is running. One way to do this is to have Docker print a table with the currently running containers:

$ docker ps

In this table, by default, you should see three entries: wordpress with port 8888, tests-wordpress with port 8889 and mariadb with port 3306.

2. Check the port number

By default wp-site uses port 8888, meaning that the local environment will be available at http://localhost:8888.

You can configure the port that wp-site uses so that it doesn't clash with another server by specifying the WP_SITE_PORT environment variable when starting wp-site:

$ WP_SITE_PORT=3333 wp-site start

Running docker ps and inspecting the PORTS column allows you to determine which port wp-site is currently using.

You may also specify the port numbers in your .wp-site.json file, but the environment variables take precedent.

3. Restart wp-site

Restarting wp-site will restart the underlying Docker containers which can fix many issues.

To restart wp-site:

$ wp-site stop
$ wp-site start

4. Restart Docker

Restarting Docker will restart the underlying Docker containers and volumes which can fix many issues.

To restart Docker:

1. Click on the Docker icon in the system tray or menu bar.
2. Select Restart.

Once restarted, start wp-site again:

$ wp-site start

5. Reset the database

Resetting the database which the local environment uses can fix many issues, especially when they are related to the WordPress installation.

To reset the database:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

$ wp-site clean all
$ wp-site start

6. Nuke everything and start again 🔥

When all else fails, you can use wp-site destroy to forcibly remove all of the underlying Docker containers and volumes. This will allow you to start from scratch.

To nuke everything:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

$ wp-site destroy
$ wp-site start

7. Debug mode and inspecting the generated dockerfile.

wp-site uses docker behind the scenes. Inspecting the generated docker-compose file can help to understand what's going on.

Start wp-site in debug mode

wp-site start --debug

wp-site will output its config which includes dockerComposeConfigPath.

ℹ Config:
	...
	"dockerComposeConfigPath": "/Users/$USERNAME/.wp-site/5a619d332a92377cd89feb339c67b833/docker-compose.yml",
	...

Command reference

wp-site creates generated files in the wp-site home directory. By default, this is ~/.wp-site. The exception is Linux, where files are placed at ~/wp-site for compatibility with Snap Packages. The wp-site home directory contains a subdirectory for each project named /$md5_of_project_path. To change the wp-site home directory, set the WP_SITE_HOME environment variable. For example, running WP_SITE_HOME="something" wp-site start will download the project files to the directory ./something/$md5_of_project_path (relative to the current directory).

wp-site start

The start command installs and initalizes the WordPress environment, which includes downloading any specified remote sources. By default, wp-site will not update or re-configure the environment except when the configuration file changes. Tell wp-site to update sources and apply the configuration options again with wp-site start --update. This will not overrwrite any existing content.

wp-site start

Starts WordPress for development on port 8888 (override with WP_SITE_PORT) and
tests on port 8889 (override with WP_SITE_TESTS_PORT). The current working
directory must be a WordPress installation, a plugin, a theme, or contain a
.wp-site.json file. After first insall, use the '--update' flag to download updates
to mapped sources and to re-apply WordPress configuration options.

Options:
  --update   Download source updates and apply WordPress configuration.
                                                      [boolean] [default: false]

wp-site stop

wp-site stop

Stops running WordPress for development and tests and frees the ports.

wp-site clean [environment]

wp-site clean [environment]

Cleans the WordPress databases.

Positionals:
  environment  Which environments' databases to clean.
            [string] [choices: "all", "development", "tests"] [default: "tests"]

wp-site run [container] [command]

wp-site run <container> [command..]

Runs an arbitrary command in one of the underlying Docker containers. For
example, it can be useful for running wp cli commands. You can also use it to
open shell sessions like bash and the WordPress shell in the WordPress instance.
For example, `wp-site run cli bash` will open bash in the development WordPress
instance.

Positionals:
  container  The container to run the command on.            [string] [required]
  command    The command to run.                           [array] [default: []]

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
  --debug    Enable debug output.                     [boolean] [default: false]

For example:

wp-site run cli wp user list
⠏ Running `wp user list` in 'cli'.

ID      user_login      display_name    user_email      user_registered roles
1       admin   admin   wordpress@example.com   2020-03-05 10:45:14     administrator

✔ Ran `wp user list` in 'cli'. (in 2s 374ms)

wp-site run tests-cli wp shell
ℹ Starting 'wp shell' on the tests-cli container. Exit the WordPress shell with ctrl-c.

Starting 31911d623e75f345e9ed328b9f48cff6_mysql_1 ... done
Starting 31911d623e75f345e9ed328b9f48cff6_tests-wordpress_1 ... done
wp> echo( 'hello world!' );
hello world!
wp> ^C
✔ Ran `wp shell` in 'tests-cli'. (in 16s 400ms)

wp-site destroy

wp-site destroy

Destroy the WordPress environment. Deletes docker containers, volumes, and
networks associated with the WordPress environment and removes local files.

wp-site logs [environment]

wp-site logs

displays PHP and Docker logs for given WordPress environment.

Positionals:
  environment  Which environment to display the logs from.
      [string] [choices: "development", "tests", "all"] [default: "development"]

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
  --debug    Enable debug output.                     [boolean] [default: false]
  --watch    Watch for logs as they happen.            [boolean] [default: true]

.wp-site.json

You can customize the WordPress installation, plugins and themes that the development environment will use by specifying a .wp-site.json file in the directory that you run wp-site from.

.wp-site.json supports six fields for options applicable to both the tests and development instances.

Note: the port number environment variables (WP_SITE_PORT and WP_SITE_TESTS_PORT) take precedent over the .wp-site.json values.

Several types of strings can be passed into the core, plugins, themes, and mappings fields.

Remote sources will be downloaded into a temporary directory located in ~/.wp-site.

Additionally, the key env is available to override any of the above options on an individual-environment basis. For example, take the following .wp-site.json file:

{
	"plugins": [ "." ],
	"config": {
		"KEY_1": true,
		"KEY_2": false
	},
	"env": {
		"development": {
			"themes": [ "./one-theme" ]
		},
		"tests": {
			"config": {
				"KEY_1": false
			},
			"port": 3000
		}
	}
}

On the development instance, cwd will be mapped as a plugin, one-theme will be mapped as a theme, KEY_1 will be set to true, and KEY_2 will be set to false. Also note that the default port, 8888, will be used as well.

On the tests instance, cwd is still mapped as a plugin, but no theme is mapped. Additionaly, while KEY_2 is still set to false, KEY_1 is overriden and set to false. 3000 overrides the default port as well.

This gives you a lot of power to change the options appliciable to each environment.

.wp-site.override.json

Any fields here will take precedence over .wp-site.json. This file is useful when ignored from version control, to persist local development overrides. Note that options like plugins and themes are not merged. As a result, if you set plugins in your override file, this will override all of the plugins listed in the base-level config. The only keys which are merged are config and mappings. This means that you can set your own wp-config values without losing any of the default values.

Default wp-config values.

On the development instance, these wp-config values are defined by default:

WP_DEBUG: true,
SCRIPT_DEBUG: true,
WP_PHP_BINARY: 'php',
WP_TESTS_EMAIL: 'admin@example.org',
WP_TESTS_TITLE: 'Test Blog',
WP_TESTS_DOMAIN: 'http://localhost',
WP_SITEURL: 'http://localhost',
WP_HOME: 'http://localhost',

On the test instance, all of the above are still defined, but WP_DEBUG and SCRIPT_DEBUG are set to false.

Additionally, the values referencing a URL include the specified port for the given environment. So if you set testsPort: 3000, port: 2000, WP_HOME (for example) will be http://localhost:3000 on the tests instance and http://localhost:2000 on the development instance.

Examples

Latest production WordPress + current directory as a plugin

This is useful for plugin development.

{
	"core": null,
	"plugins": [ "." ]
}

Latest development WordPress + current directory as a plugin

This is useful for plugin development when upstream Core changes need to be tested.

{
	"core": "WordPress/WordPress#master",
	"plugins": [ "." ]
}

Local wordpress-develop + current directory as a plugin

This is useful for working on plugins and WordPress Core at the same time.

{
	"core": "../wordpress-develop/build",
	"plugins": [ "." ]
}

A complete testing environment

This is useful for integration testing: that is, testing how old versions of WordPress and different combinations of plugins and themes impact each other.

{
	"core": "WordPress/WordPress#5.2.0",
	"plugins": [ "WordPress/wp-lazy-loading", "WordPress/classic-editor" ],
	"themes": [ "WordPress/theme-experiments" ]
}

Add mu-plugins and other mapped directories

You can add mu-plugins via the mapping config. The mapping config also allows you to mount a directory to any location in the wordpress install, so you could even mount a subdirectory. Note here that theme-1, will not be activated, despite being the "first" mapped theme.

{
	"plugins": [ "." ],
	"mappings": {
		"wp-content/mu-plugins": "./path/to/local/mu-plugins",
		"wp-content/themes": "./path/to/local/themes",
		"wp-content/themes/specific-theme": "./path/to/local/theme-1"
	}
}

Avoid activating plugins or themes on the instance

Since all plugins in the plugins key are activated by default, you should use the mappings key to avoid this behavior. This might be helpful if you have a test plugin that should not be activated all the time. The same applies for a theme which should not be activated.

{
	"plugins": [ "." ],
	"mappings": {
		"wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
	}
}

Map a plugin only in the tests environment

If you need a plugin active in one environment but not the other, you can use env.<envName> to set options specific to one environment. Here, we activate cwd and a test plugin on the tests instance. This plugin is not activated on any other instances.

{
	"plugins": [ "." ],
	"env": {
		"tests": {
			"plugins": [ ".", "path/to/test/plugin" ]
		}
	}
}

Custom Port Numbers

You can tell wp-site to use a custom port number so that your instance does not conflict with other wp-site instances.

{
	"plugins": [ "." ],
	"port": 4013,
	"env": {
		"tests": {
			"port": 4012
		}
	}
}