librarian-puppet update
[project/drush-vagrant.git] / README.md
1 DESCRIPTION
2 -----------
3
4 Drush Vagrant Integration provides Drush commands to accomplish common Vagrant
5 tasks, and provides a powerful templating framework ('blueprints'). It also has
6 tools to implement Drush aliases for Vagrant projects and VMs, thus allowing
7 simpler remote control of Vagrant projects.
8
9 Drush Vagrant is intended to simplify building collaborative, distributed
10 development and testing environments, that encourage the use of Drupal best-
11 practices. Projects can easily be cloned and shared via Git, or even bundled
12 into blueprints that others can use as templates for their own development
13 environments.
14
15 While initially developed (via the Aegir-up project) as a Drupal and Aegir
16 development tool, Drush Vagrant itself is not Drupal-specific. It provides
17 generally useful wrappers around Vagrant, and can thus assist in building and
18 testing non-Drupal projects, such as Puppet modules.
19
20 DEPENDENCIES
21 ------------
22
23 Drush Vagrant Integration (obviously) depends on Drush and Vagrant (which in
24 turn depends on VirtualBox, and possibly Ruby and RubyGems). Some features also
25 require an NFS server.
26
27 Vagrant 1.0+ is required, and installation instructions can be found at:
28 http://vagrantup.com/v1/docs/getting-started/index.html
29
30 A recent version of VirtualBox (4.0+) is required by Vagrant, and can be
31 downloaded from: https://www.virtualbox.org/wiki/Downloads.
32
33 Drush 5.x or greater is required. Drush can be installed in a number of ways,
34 as detailed here:
35 http://drupalcode.org/project/drush.git/blob/HEAD:/README.txt#l30. Drush Hosts
36 (http://drupal.org/project/drush-hosts) is also required in order to manage
37 entries in /etc/hosts during project builds and deletion.
38
39 Compatible releases of Vagrant, VirtualBox and Drush are available in Debian's
40 Testing branch, and so can be installed (along with all dependencies) with a
41 simple 'apt-get install vagrant drush', assuming the appropriate repos have
42 been added to /etc/apt/source.list.d/ This last is the developers' preferred
43 and recommended installation method.
44
45 In order to take advantage of Vagrant's ability to mount NFS (Network File
46 System) shares, an NFS-server is required. This allows the sharing of entire
47 directory trees transparently between the host machine and the VM. If it isn't
48 already, a recent version should be easy to install using your OS's preferred
49 packaging method. For Debian-like systems, this means something like: 'apt-get
50 install nfs-kernel-server'.
51
52 Finally, some blueprints may require a custom Vagrant base box. This will be
53 automatically downloaded upon first use of that blueprint. Base boxes are
54 usually built with a Vagrant plugin called veewee (https://github.com/jedi4ever/veewee),
55 and all definitions needed to build a base box should be included within the
56 blueprint's project. Note that building a base box is not required for the use
57 of Drush Vagrant.
58
59
60 INSTALLATION
61 ------------
62
63 Installation should be as simple as:
64
65   drush dl drush-vagrant drush-hosts
66
67 This should create a folder at ~/.drush/drush-vagrant, but might also be
68 installed to /path/to/drush/commands/drush-vagrant, depending on how Drush was
69 itself installed.
70
71 Permission issues during installation can be overcome by running the command as
72 root:
73
74   sudo drush dl drush-vagrant drush-hosts
75
76 Or downloading it to your personal .drush folder:
77
78   cd ~
79   mkdir .drush
80   drush dl drush-vagrant drush-hosts --destination=./.drush
81
82 When a Drush Vagrant project is first initialized, user settings are
83 automatically saved to ~/.drushrc.php. By default, it will use the Vagrant
84 'projects' folder usually located at ~/vagrant/projects. User settings can be
85 modified by running 'drush vagrant-user' (or 'drush vuser') at any time.
86
87 Now that Vagrant is available in Debian (Testing), .deb packaging is planned,
88 to further simplify installation.
89
90
91 USAGE
92 -----
93
94 Usage documentation is in Drush's built-in help system. To see a list of
95 Drush Vagrant commands, you can run the following:
96
97   drush --filter=vagrant
98
99 More detailed usage information is provided by running:
100
101   drush <command> --help
102
103
104 QUICK START
105 -----------
106
107 Build a new VM:
108   drush vagrant-build
109
110 Change into the new vagrant project directory:
111   cd ~/vagrant/project/new-vagrant-project
112
113 SSH into the new VM:
114   drush vagrant-shell
115
116
117 NEXT STEPS
118 ----------
119
120 By itself, Drush-vagrant will only provide a 'default' blueprint. You'll proba-
121 bly be interested in checking out these blueprints:
122
123 http://drupal.org/project/drupal-up  (drush dl drupal-up)
124 http://drupal.org/project/aegir-up   (drush dl aegir-up)
125
126 OTHER DOCS & HELP
127 -----------------
128
129 More detailed documentation can be found in the docs/ folder, which are also
130 available as Drush topics:
131
132   drush topic
133
134 Bug reports, feature and support requests should be submitted to the drupal.org
135 issue queue: http://drupal.org/project/issues/drush-vagrant
136
137 Also, the developers (See Credits section, below) can usually be found on IRC
138 in the #aegir and #openatria channels on irc.freenode.net.
139
140
141 CREDITS
142 -------
143
144 Originally developed by Steven Merrill <http://www.stevenwmerrill.com/>
145 The 2.x branch was developed by Christopher Gervais <http://ergonlogic.com/>
146 and is maintained by Christopher Gervais and Herman Van Rink (helmo)