Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 103 lines (56 sloc) 5.37 kB
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
1 Using Vagrant for development
2 =============================
3
681478f @igal Improve VAGRANT.md documentation, and explain overrides.
igal authored
4 [Vagrant](http://vagrantup.com/) is a tool used by this project to provide you with a complete, working copy of the development environment. Using Vagrant will make it easier and faster to begin working on this project than if you were to try to set everything up yourself. Vagrant works by creating a virtual machine -- an isolated operating system that runs within your normal operating system. This virtual machine has been specially prepared to include everything needed to develop and run the application.
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
5
6 Setup
7 -----
8
9 Setup Vagrant and its dependencies:
10
11 1. Install Ruby: [http://www.ruby-lang.org/](http://www.ruby-lang.org/)
12 2. Install Rubygems: [http://rubygems.org/pages/download](http://rubygems.org/pages/download)
13 3. Install VirtualBox: [http://www.virtualbox.org/](http://www.virtualbox.org/)
14 4. Install Vagrant:
15
16 gem install vagrant
17
18 Usage
19 -----
20
d5764c8 @igal Improve VAGRANT.md documentation.
igal authored
21 Working with a Vagrant environment requires interacting with your local operating system AND the virtual machine. You will use your local machine to access the web application at [http://localhost:8000/](http://localhost:8000/), edit files, and do version control. You will use your virtual machine to run `bundle exec rake` and other commands that need the development environment.
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
22
d5764c8 @igal Improve VAGRANT.md documentation.
igal authored
23 Use Vagrant by issuing the commands below. The `local%` and `virtual%` in the commands are just indicators to show which machine to enter commands into, you shouldn't actually type them -- thus `local% pwd` means that you should run `pwd` on your local machine.
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
24
25 **Start** the virtual machine, which will take some time to download the first time:
26
27 local% vagrant up
28
86ebb08 @igal Update Vagrant provisioning to not start the Rails application on boot.
igal authored
29 **Access** the application running on the virtual machine by visiting -- it won't be running until you start it though:
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
30
31 http://localhost:8000/
32
33 **SSH** into the virtual machine and go into the directory containing the application:
34
35 local% vagrant ssh
b421b74 @igal Improve Vagrant to automatically `cd /vagrant` when doing `vagrant ssh`.
igal authored
36
37 **Run** the application on the virtual machine, it will be accessible on [http://localhost:8000/](http://localhost:8000/):
38
39 local% vagrant ssh
f5034a1 @igal Update documentation for Rails 3.
igal authored
40 virtual% rails server
aa03108 @igal Add Vagrant support, see VAGRANT.md for instructions.
igal authored
41
42 **Test** the application within the virtual machine:
43
44 local% vagrant ssh
45 virtual% bundle exec rake
46
47 **Reload** the virtual machine, needed if you changed the `Gemfile` or `config` files, or used a revision control command that updated them:
48
49 local% vagrant reload
50
51 **Suspend** the virtual machine, quickly pausing it when you're done and freeing up memory:
52
53 local% vagrant suspend
54
55 **Resume** the virtual machine, quickly resuming a suspended virtual machine:
56
57 local% vagrant resume
58
59 **Destroy** the virtual machine if you don't need it any more and want to free up disk space -- don't worry, you can always `vagrant up` to recreate it later:
60
61 local% vagrant destroy
681478f @igal Improve VAGRANT.md documentation, and explain overrides.
igal authored
62
63 Advanced settings
64 -----------------
65
66 ### Virtual machine
67
68 You can customize some settings on your virtual machine by creating a `Vagrantfile.local` file. This file is local to your computer and should not be added to revision control.
69
70 The overrides are written in Ruby and included by the `Vagrantfile` if found. These overrides are applied when you start a virtual machine with `vagrant up` or any time you run `vagrant reload`.
71
72 Below are the supported overrides:
73
74 * Forward the virtual machine's port 80 to the local machine's port 8080:
75
76 HTTP_PORT = 8080
77
78 * Forward the virtual machine's port 3000 to the local machine's port 8000:
79
80 RAILS_PORT = 8000
81
d5764c8 @igal Improve VAGRANT.md documentation.
igal authored
82 * Share files from the local machine to the virtual machine using NFS, which is much faster than the default sharing mechanism. Unfortunately, there are a few gotchas. You must provision the virtual machine initially without NFS so the NFS client can be installed, then you can enable NFS and run `vagrant reload` so you can begin using it. You must be running a UNIX-like operating system as your local machine, have an NFS server installed, and have `root` access via `sudo` for Vagrant to automatically configure NFS sharing.
681478f @igal Improve VAGRANT.md documentation, and explain overrides.
igal authored
83
84 NFS = true
85
86 * Set the virtual machine's IP address to `33.33.31.13`, which is useful if you want to SSH into the virtual machine by IP, rather than using `vagrant ssh`. If you're not using overrides to set the address or enable NFS, the address will be randomly assigned by VirtualBox.
87
88 ADDRESS = "33.33.31.13"
89
f853cbf @igal Improve Vagrantfile, allow user to override memory alloted to VM.
igal authored
90 * Set the amount of memory to dedicate to the virtual machine to 512 megabytes. The appropriate amount will depend on how much memory you have available versus how much processes within the virtual machine need. In general, running `bundler` or `gem` in the virtual machine will require at least 512 megabytes:
91
92 MEMORY = 512
93
681478f @igal Improve VAGRANT.md documentation, and explain overrides.
igal authored
94 ### Provisioning
95
96 You can customize your virtual machine by creating a `vagrant/cookbooks/vagrant/recipes/local.rb` file. This file is local to your computer and should not be added to revision control.
97
98 This file can contain any valid Chef recipe code, and will be applied when a virtual machine is first created using `vagrant up` or any time you run `vagrant reload`. This custom code will be run after all the other operating system packages have been installed, but before Bundler is run -- see `vagrant/cookbooks/vagrant/recipes/default.rb` for additional context.
99
100 For example, you could add the following to install the `emacs` package on your virtal machine:
101
102 package "emacs"
Something went wrong with that request. Please try again.