vagrant: Add option to specify system settings.

Two variables were declared and assigned the respective values of the
default settings for the system. If the keyword is used in the
~/.zulip-vagrant-config file, the value is assigned to the variable.

There is no straightforward way to customize the virtual machine's
number of cpus or memory, this commit addresses that fact.

Vagrantfile

@@ -76,6 +76,10 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
   http_proxy = https_proxy = no_proxy = nil
   host_ip_addr = "127.0.0.1"
 
+  # System settings for the virtual machine.
+  vm_num_cpus = "2"
+  vm_memory = "2048"
+
   config.vm.synced_folder ".", "/vagrant", disabled: true
   if (/darwin/ =~ RUBY_PLATFORM) != nil
     config.vm.synced_folder ".", "/srv/zulip", type: "nfs",
@@ -97,6 +101,8 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
       when "NO_PROXY"; no_proxy = value
       when "HOST_PORT"; host_port = value.to_i
       when "HOST_IP_ADDR"; host_ip_addr = value
+      when "GUEST_CPUS"; vm_num_cpus = value
+      when "GUEST_MEMORY_MB"; vm_memory = value
       end
     end
   end
@@ -143,14 +149,14 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
   config.vm.provider "virtualbox" do |vb, override|
     override.vm.box = "ubuntu/trusty64"
     # It's possible we can get away with just 1.5GB; more testing needed
-    vb.memory = 2048
+    vb.memory = vm_memory
-    vb.cpus = 2
+    vb.cpus = vm_num_cpus
   end
 
   config.vm.provider "vmware_fusion" do |vb, override|
     override.vm.box = "puphpet/ubuntu1404-x64"
-    vb.vmx["memsize"] = "2048"
+    vb.vmx["memsize"] = vm_memory
-    vb.vmx["numvcpus"] = "2"
+    vb.vmx["numvcpus"] = vm_num_cpus
   end
 
 $provision_script = <<SCRIPT

docs/development/setup-vagrant.md

@@ -18,6 +18,7 @@ Contents:
 * [Step 4: Developing](#step-4-developing)
 * [Troubleshooting and Common Errors](#troubleshooting-and-common-errors)
 * [Specifying a proxy](#specifying-a-proxy)
+* [Customizing CPU and RAM allocation](#customizing-cpu-and-ram-allocation)
 
 **If you encounter errors installing the Zulip development
 environment,** check
@@ -1091,6 +1092,45 @@ HOST_IP_ADDR 0.0.0.0
 (and restart the Vagrant guest), your host IP would be 0.0.0.0, a special value
 for the IP address that means any IP address can connect to your development server.
 
+### Customizing CPU and RAM allocation
+
+When running Vagrant using a VM-based provider such as VirtualBox or
+VMWare Fusion, CPU and RAM resources must be explicitly allocated to
+the guest system (with LXC and other container-based Vagrant
+providers, explicit allocation is unnecessary and the settings
+described here are ignored).
+
+Our default Vagrant settings allocate 2 cpus with 2GiB of memory for
+the guest, which is sufficient to run everything in the development
+environment.  If your host system has more CPUs, or you have enough
+RAM that you'd like to allocate more than 2GiB to the guest, you can
+improve performance of the Zulip development environment by allocating
+more resources.
+
+To do so, create a `~/.zulip-vagrant-config` file containing the
+following lines:
+
+```
+GUEST_CPUS <number of cpus>
+GUEST_MEMORY_MB <system memory (in MB)>
+```
+
+For example:
+
+```
+GUEST_CPUS 4
+GUEST_MEMORY_MB 8192
+```
+
+would result in an allocation of 4 cpus and 8 GiB of memory to the
+guest VM.
+
+After changing the configuration, run `vagrant reload` to reboot the
+guest VM with your new configuration.
+
+If at any time you wish to revert back to the default settings, simply
+remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from
+`~/.zulip-vagrant-config`.
 
 [cygwin-dl]: http://cygwin.com/
 [vagrant-dl]: https://www.vagrantup.com/downloads.html