Calypso Bootstrap

Calypso Bootstrap is a portable development environment for Calypso, the powerful administration interface of WordPress.com. It allows you to install, configure, and start a virtual machine that is ready to run Calypso - with a single command. This sandbox makes it very easy to learn about, test, and hack Calypso without messing with the configuration of your computer. It uses some cool technologies such as Vagrant, Puppet, and VirtualBox under the hood.

Check out Calypso Bootstrap (WSL) if you specifically want to run Calypso on Windows, as it has better performance.

Prerequisites

You need to have the following software already installed:

Note you should be able to use another virtual machine provider, but currently only VirtualBox is supported.

Make sure Vagrant is available from your terminal or console with:

$ vagrant version

Installed Version: 1.8.1
Latest Version: 1.8.1

Installing

Installing Calypso is very easy - just load a terminal or console and:

Clone the Calypso Bootstrap repository to your computer
Go to your fresh new Calypso Bootstrap directory
Type vagrant up to bring the sandbox to life

On Linux, it will probably look like this:

$ git clone https://github.com/Automattic/wp-calypso-bootstrap.git
$ cd wp-calypso-bootstrap
$ vagrant up

On Windows, it's going to be very similar:

C:\>git clone https://github.com/Automattic/wp-calypso-bootstrap.git
C:\>cd wp-calypso-bootstrap
C:\wp-calypso-bootstrap>vagrant up

Note this installation process can take quite some time the first time you perform a vagrant up since it will basically:

Download an image of the current stable version of Ubuntu
Load it into the virtual machine and update it
Install all necessary packages such as Git, Node.js, or Yarn
Download the Calypso repository

Finally, just add 127.0.0.1 calypso.localhost to your hosts file.

Running

You should have a virtual machine up and running by now. The next step is simply to connect to this sandbox via SSH with your favorite terminal or console, either by typing vagrant ssh, or using the following parameters:

Host name: 127.0.0.1
Port: 2222
User name: vagrant
User password: vagrant

These parameters should be pretty standard. However, if you encounter any issues connecting to the virtual machine, you can check them with the vagrant ssh-config command.

Note your SSH client should be configured to allow SSH agent forwarding if you want to be able to use your local SSH keys to connect to GitHub from inside the virtual machine (using agents such as ssh-agent or Pageant).

You should then be presented with something similar to the following:

             _
    ___ __ _| |_   _ _ __  ___  ___
   / __/ _` | | | | | '_ \/ __|/ _ \
  | (_| (_| | | |_| | |_) \__ \ (_) |
   \___\__,_|_|\__, | .__/|___/\___/
               |___/|_|

   Welcome to WordPress.com goodness

vagrant@calypso:~$

Now simply head to the Calypso directory:

vagrant@calypso:~$ cd /var/sources

And install dependencies with:

vagrant@calypso:/var/sources$ yarn

Start the application with:

vagrant@calypso:/var/sources$ yarn start

This will build Calypso, which can be a lengthy process. Hopefully at some point you'll see:

Ready! You can load http://calypso.localhost:3000/ now. Have fun!

You should now be able to access Calypso in your browser at http://calypso.localhost:3000!

Hacking

The Calypso repository is located in /var/sources on the virtual machine. This isn't a shared folder, i.e. a directory that is shared between the virtual machine (the guest system) and your own computer (the host system). This was done for performance reason as well as to work around a number of limitations (most of them originating from running Windows as host system).

With Calypso Bootstrap you can either work from the virtual machine itself or from your computer. In the former case, you would edit files in the /var/sources folder directly. In the latter, you would have to sync this folder to your computer using a tool such as rsync or unison (which is installed by default). From there, you would be able to edit files using your favorite code editor.

Relaxing

You can shutdown the virtual machine with vagrant halt and start it again with vagrant up. You can also pause it with vagrant suspend and unpause it with vagrant resume.

Good job, you deserve a cup of coffee now!

Troubleshooting

If you encounter any issues, check Calypso's readme and documentation. If you're still stuck, we're here to help.

License

Calypso Bootstrap is licensed under GNU General Public License v2 (or later).

Automattic / wp-calypso-bootstrap

readme