Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Getting Started Docs: Update to use wp-env #20044

Merged
merged 3 commits into from
Feb 10, 2020
+9 −41
Merged

Getting Started Docs: Update to use wp-env #20044

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83ef9cb
Getting Started Docs: Update to use
ockham Feb 10, 2020
743c26c
Link to .wp-env.json to use local WP install
ockham Feb 10, 2020
65f5ad0
Update note on debug systems
ockham Feb 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ This repo is the development hub for the <a href="https://make.wordpress.org/cor
- **Download:** If you want to use the latest release with your WordPress site, <a href="https://wordpress.org/plugins/gutenberg/">download the latest release from the WordPress.org plugins repository</a>.
- **Discuss:** Conversations and discussions take place in <a href="https://wordpress.slack.com/messages/C02QB2JS7">`#core-editor` channel on the Making WordPress Slack</a>.
- **Contribute:** Development of Gutenberg happens in this GitHub repo. Get started by <a href="https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md">reading the contributing guidelines</a>.
- **Develop:** Just want to run Gutenberg locally to tinker with it? See <a href="https://github.com/WordPress/gutenberg/blob/master/docs/contributors/getting-started.md">Getting Started</a>.
- **Learn:** <a href="https://wordpress.org/gutenberg/">Discover more about the project on WordPress.org</a>.

**Gutenberg is more than an editor.** While the project is currently focused on building the new editor for WordPress, it doesn't end there. This lays the groundwork for a new model for WordPress Core that will ultimately impact the entire publishing experience of the platform.
Expand Down
49 changes: 8 additions & 41 deletions docs/contributors/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ If you don't have a local WordPress environment to load Gutenberg in, we can hel

### Step 1: Installing a Local Environment

#### Quickest Method: Using Docker
The quickest way to get up and running is to use the [`wp-env` command](https://github.com/WordPress/gutenberg/tree/master/packages/env), which is developed within the Gutenberg source repository, and published as `@wordpress/env` to npm. In its default mode, it'll install and run a local WordPress environment for you; however, it's also possible to [configure](https://github.com/WordPress/gutenberg/blob/master/packages/env/README.md#wp-envjson) it to use a pre-existing local WordPress installation.

The quickest way to get up and running is to use the provided Docker setup. If you don't already have it, you'll need to install Docker and Docker Compose.
If you don't already have it, you'll need to install Docker and Docker Compose in order to use `wp-env`.

To install Docker, follow their instructions here for [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other version of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), or [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If running Ubuntu, see these [extended instructions for help and troubleshooting](/docs/contributors/env-ubuntu.md).

Expand All @@ -32,58 +32,25 @@ To install Docker Compose, [follow their instructions here](https://docs.docker.
Once Docker is installed and running, run this script to install WordPress, and build your local environment:

```bash
npm run env install
npx wp-env start
```

#### Alternative Method: Using an Existing Local WordPress Install
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the entire section since I wasn't how to fit this in the bigger picture anymore; I had to modify a lot of the commands in subsequent sections to use wp-env, which wouldn't work with the instructions in this section. Okay to retire the alternative method section?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wp-env does support this with the config file PR. We might want to mention it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 743c26c :)


WordPress will be installed in the `wordpress` directory, if you need to access WordPress core files directly, you can find them there.

If you already have WordPress checked out in a different directory, you can use that installation, instead, by running these commands:

```bash
export WP_DEVELOP_DIR=/path/to/wordpress-develop
npm run env connect
```

This will use WordPress' own local environment, and mount your Gutenberg directory as a volume there.

In Windows, you can set the `WP_DEVELOP_DIR` environment variable using the appropriate method for your shell:

- CMD: `set WP_DEVELOP_DIR=/path/to/wordpress-develop`
- PowerShell: `$env:WP_DEVELOP_DIR = "/path/to/wordpress-develop"`

### Step 2: Accessing and Configuring the Local WordPress Install

#### Accessing the Local WordPress Install

Whether you decided to use Docker or an existing local WordPress install, the WordPress installation should now be available at `http://localhost:8889` (**Username**: `admin`, **Password**: `password`).
If this port is in use, you can override it using the `LOCAL_PORT` environment variable. For example running the below command on your computer will change the URL to
`http://localhost:7777` .

Linux/macOS: `export LOCAL_PORT=7777`
Windows using Command Prompt: `setx LOCAL_PORT "7777"`
Windows using PowerShell: `$env:LOCAL_PORT = "7777"`
The WordPress installation should now be available at `http://localhost:8888` (**Username**: `admin`, **Password**: `password`).
If this port is in use, you can override it using the `WP_ENV_PORT` environment variable. For more information, consult the `wp-env` [README](https://github.com/WordPress/gutenberg/blob/master/packages/env/README.md).

If you're running [e2e tests](/docs/contributors/testing-overview.md#end-to-end-testing), this change will be used correctly.

To shut down this local WordPress instance run `npm run env stop`. To start it back up again, run `npm run env start`.
To shut down this local WordPress instance run `npx wp-env stop`. To start it back up again, run `npx wp-env start` again.

#### Toggling Debug Systems

WordPress comes with specific [debug systems](https://wordpress.org/support/article/debugging-in-wordpress/) designed to simplify the process as well as standardize code across core, plugins and themes. It is possible to use environment variables (`LOCAL_WP_DEBUG` and `LOCAL_SCRIPT_DEBUG`) to update a site's configuration constants located in `wp-config.php` file. Both flags can be disabled at any time by running the following command:

Example on Linux/MacOS:

```bash
LOCAL_SCRIPT_DEBUG=false LOCAL_WP_DEBUG=false npm run env install
```

By default, both flags will be set to `true`.
WordPress comes with specific [debug systems](https://wordpress.org/support/article/debugging-in-wordpress/) designed to simplify the process as well as standardize code across core, plugins and themes. In order to use with `wp-env,` you'll have to edit your local WordPress install's `wp-config.php`.

#### Troubleshooting

You might find yourself stuck on a screen stating that "you are running WordPress without JavaScript and CSS files". If you tried installing WordPress via `npm run env install`, it probably means that something went wrong during the process. To fix it, try removing the `/wordpress` folder and running `npm run env install` again.
See the [relevant section in `wp-env` docs](https://github.com/WordPress/gutenberg/tree/master/packages/env#troubleshooting-common-problems).

## On A Remote Server

Expand Down