Update documentation around alternate installation option

Automattic · 24afd2eaf709c2d4a1289a8ec0597d58f33ffe02 · stephanethomas committed Jan 23, 2017 · Jan 23, 2017 · 24afd2e
1 parent 82b55fd
commit 24afd2eaf709c2d4a1289a8ec0597d58f33ffe02
Unified Split

Showing with 24 additions and 41 deletions.

+2 −2 README.md

+11 −9 docs/install.md

+11 −30 docs/windows.md
diff --git a/README.md b/README.md
@@ -14,9 +14,9 @@ You can try out the user-side of Calypso on [WordPress.com](https://wordpress.co
 
 1.	Make sure you have `git`, `node`, and `npm` installed.
 2.	Clone this repository locally.
-3.	Add `127.0.0.1 calypso.localhost` to your local hosts file.
+3.	Add `127.0.0.1 calypso.localhost` to your local `hosts` file.
 4.	Execute `make run` or `make dashboard` (for a more visually-oriented interface) from the root directory of the repository.
-5.	Open `calypso.localhost:3000` in your browser.
+5.	Open [`calypso.localhost:3000`](http://calypso.localhost:3000/) in your browser.
 
 Need more detailed installation instructions? [We have them](docs/install.md).
 
diff --git a/docs/install.md b/docs/install.md
@@ -1,26 +1,28 @@
 # Installing Calypso
 
+You can install Calypso directly on your machine by following the next steps, or use a [portable development environment](install.md#using-a-portable-development-environment):
+
 ## Quick Summary of Steps
 
-1.	Check that you have all prerequisites (Git, Node, NPM). See below for more details.
+1.	Check that you have all prerequisites (Git, Node, NPM). See [below](install.md#prerequisites) for more details.
 2.	Clone this repository locally.
-3.	Add `127.0.0.1 calypso.localhost` to your local hosts file.
-4.	Execute `make run` from the directory of the repository.
-5.	Open `calypso.localhost:3000` in your browser.
+3.	Add `127.0.0.1 calypso.localhost` to your local `hosts` file.
+4.	Execute `make run` or `make dashboard` (for a more visually-oriented interface) from the root directory of the repository.
+5.	Open [`calypso.localhost:3000`](http://calypso.localhost:3000/) in your browser.
 
 ## Prerequisites
 
-To be able to clone the repo and run the application **on Mac OS X or Linux** you need:
+**On Mac OS X or Linux**, to be able to clone the repository and run the application you need:
 
 -	Install the [Node.js](http://nodejs.org/) and matching [NPM](https://www.npmjs.com/) [versions](https://nodejs.org/en/download/releases/) listed in the engines section of [package.json](https://github.com/Automattic/wp-calypso/blob/master/package.json). On Mac OS X using [nvm](https://github.com/creationix/nvm) or [n](https://github.com/tj/n) makes it easy to manage `node` versions.
 -	[Git](http://git-scm.com/). Try the `git` command from your terminal, if it's not found then use this [installer](http://git-scm.com/download/).
 -	The repository also uses `make` to orchestrate compiling the JavaScript, running the server, and several other tasks. On Mac OS X, the easiest way to install `make` is through Apple's [Command Line Tools for Xcode](https://developer.apple.com/downloads/) (requires free registration).
 
-**On Windows**, please follow [these setup steps](windows.md) to install the prerequisites, or see the [alternate install](install.md#alternate-install-vagrant) instructions further down.
+**On Windows**, you can follow [these setup steps](windows.md) to install the prerequisites.
 
 ## Installing and Running
 
-Clone this git repo to your machine via the terminal using the `git clone` command and then run `make run` from the root Calypso directory:
+Clone this git repository to your machine via the terminal using the `git clone` command and then run `make run` from the root Calypso directory:
 
 ```bash
 $ git clone https://github.com/Automattic/wp-calypso.git
@@ -32,6 +34,6 @@ The `make run` command will install any `npm` dependencies and start the develop
 
 To run Calypso locally, you'll need to add `127.0.0.1 calypso.localhost` to [your hosts file](http://www.howtogeek.com/howto/27350/beginner-geek-how-to-edit-your-hosts-file/), and load the app at [http://calypso.localhost:3000](http://calypso.localhost:3000) instead of just `localhost`. This is necessary, because when running locally Calypso is using the remote version of the WordPress.com REST API, which allows only certain origins via our current authentication methods.
 
-## Alternate install: Vagrant
+## Using a portable development environment
 
-Building Calypso natively is fairly easy on Mac OS but a bit of a pain on Windows. Luckily there's the awesome [`wp-calypso-bootstrap`](https://github.com/Automattic/wp-calypso-bootstrap) alternative development environment (using Vagrant and Puppet). This tool enables you to `vagrant up` and run Calypso quickly on Windows.
+You can install Calypso very quickly via a portable development environment called [Calypso Bootstrap](https://github.com/Automattic/wp-calypso-bootstrap). It uses Vagrant and Puppet behind the scenes to install and configure a virtual machine with Calypso ready to run - with a single command.
diff --git a/docs/windows.md b/docs/windows.md
@@ -1,31 +1,24 @@
 # Installing Calypso on Windows
 
-The set up for Windows is a bit more complicated than if you were on a \*nix
-system. This is because Node.js does not build under Cygwin or MinGW anymore,
-so we are stuck with the Windows build which uses Windows-style paths
-(`C:\Windows\system`), while most of our build utilities use Unix style paths
-(`/home/stuff/here`) and they don't play well together.
+The set up for Windows is a bit more complicated than if you were on a \*nix system. This is because Node.js does not build under Cygwin or MinGW anymore, so we are stuck with the Windows build which uses Windows-style paths (`C:\Windows\system`), while most of our build utilities use Unix style paths (`/home/stuff/here`) and they don't play well together.
 
-This is a complicated configuration and it's important to follow all
-instructions and settings in the guide.  In particular, when installing any of
-the following tools, be sure to use paths that do not have spaces in them.
+> You can use a [portable development environment](https://github.com/Automattic/wp-calypso-bootstrap) to avoid going through all of the following: it will setup a virtual machine with Calypso ready to run for you.
 
-1. Install [Git for Windows](https://git-scm.com/download/win).  Make the
-   following changes to the default settings:
+This is a complicated configuration and it's important to follow all instructions and settings in the guide. In particular, when installing any of the following tools, be sure to use paths that do not have spaces in them.
+
+1. Install [Git for Windows](https://git-scm.com/download/win). Make the following changes to the default settings:
    - Install to a path without spaces<br>
      <img width="450" src="https://cloud.githubusercontent.com/assets/227022/12865564/5094f920-cc75-11e5-9230-67c17fbaaa69.png">
    - Select "Use Git from the Windows Command Prompt"<br>
      <img width="450" src="https://cloud.githubusercontent.com/assets/227022/12865563/509471ee-cc75-11e5-91ac-68496802029f.png">
 
-2. Install [Node.js](https://nodejs.org/en/download/) through the normal
-   Windows installer.  Make the following changes to the default settings:
+2. Install [Node.js](https://nodejs.org/en/download/) through the normal Windows installer. Make the following changes to the default settings:
    - Install to a path without spaces<br>
      <img width="450" src="https://cloud.githubusercontent.com/assets/227022/12865565/50953368-cc75-11e5-9b77-5ecd78f1d005.png">
 
 3. Install [MSYS2](https://msys2.github.io/).  The default settings are fine.
 
-4. For the following commands and generally for working with Calypso, use the
-   `MSYS2 Shell` that's been added to your `Start` menu.
+4. For the following commands and generally for working with Calypso, use the `MSYS2 Shell` that's been added to your `Start` menu.
 
 5. Make sure to follow the installation instructions for MSYS2 and update:
     ```
@@ -39,32 +32,20 @@ the following tools, be sure to use paths that do not have spaces in them.
     pacman -S make
     ```
 
-7. Make sure that `git` is available and the Windows version is used (do *not*
-   install `git` from MSYS2).  Also, double check that the reported path does
-   not contain spaces.
+7. Make sure that `git` is available and the Windows version is used (do *not* install `git` from MSYS2).  Also, double check that the reported path does not contain spaces.
     ```
     which git
 	/c/git/cmd/git
     ```
 
-8. And you're done - you can follow
-   [the normal instructions](https://github.com/Automattic/wp-calypso/blob/master/docs/install.md#installing-and-running)
-   from now on!
+8. And you're done - you can follow [the normal instructions](https://github.com/Automattic/wp-calypso/blob/master/docs/install.md#installing-and-running) from now on!
 
-The development setup for Calypso uses
-[`socket.io`](https://github.com/socketio/socket.io),
-which has some native dependencies.  These are *optional*, but because native
-addons via `node-gyp` are problematic on both Windows and MSYS (see `node-gyp`
-[#629](https://github.com/nodejs/node-gyp/issues/629),
-[#740](https://github.com/nodejs/node-gyp/issues/740)),
-you may see some errors as they try to build.  As long as they are all related
-to warning messages like the following:
+The development setup for Calypso uses [`socket.io`](https://github.com/socketio/socket.io), which has some native dependencies.  These are *optional*, but because native addons via `node-gyp` are problematic on both Windows and MSYS (see `node-gyp` [#629](https://github.com/nodejs/node-gyp/issues/629), [#740](https://github.com/nodejs/node-gyp/issues/740)), you may see some errors as they try to build.  As long as they are all related to warning messages like the following:
 
 ```
 npm WARN optional dep failed, continuing [email protected]
 npm WARN optional dep failed, continuing [email protected]
 npm WARN optional dep failed, continuing [email protected]
 ```
 
-then this should only affect the performance of the `socket.io` library, not
-its functionality.
+Then this should only affect the performance of the `socket.io` library, not its functionality.