From 054679a24edf296024c7279ec3ef17ec39eda9aa Mon Sep 17 00:00:00 2001 From: Louise Crow Date: Wed, 30 Jul 2014 09:35:37 +0100 Subject: Add documentation on installing with Vagrant. --- docs/installing/vagrant.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/installing/vagrant.md (limited to 'docs/installing/vagrant.md') diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md new file mode 100644 index 000000000..65be1be51 --- /dev/null +++ b/docs/installing/vagrant.md @@ -0,0 +1,67 @@ +--- +layout: page +title: Vagrant +--- +# Alaveteli using Vagrant + +

+Vagrant provides an easy method to set up virtual development environments; for +further information see the Vagrant website. +We bundle an example Vagrantfile in the repository, which runs the +install script for you. +

+ +Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). + +The included steps will use vagrant to create a development environment +where you can run the test suite, the development server and make +changes to the codebase. + +The basic process is to create a base virtual machine, and then +provision it with the software packages and setup needed. The supplied +scripts will create you a Vagrant VM based on the server edition of +Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. + +1. Get a copy of Alaveteli from GitHub and create the Vagrant instance. + This will provision the system and can take some time - usually at + least 20 minutes. + + # on your machine + $ git clone git@github.com:mysociety/alaveteli.git + $ cd alaveteli + $ git submodule update --init + $ vagrant --no-color up + +2. You should now be able to ssh in to the Vagrant guest OS and run the + test suite: + + $ vagrant ssh + + # You are now in a terminal on the virtual machine + $ cd /home/vagrant/alaveteli + $ bundle exec rake spec + + +3. Run the rails server and visit the application in your host browser + at http://10.10.10.30:3000 + + # in the virtual machine terminal + bundle exec rails server + + +# Customizing the Vagrant instance + +The Vagrantfile allows customisation of some aspects of the virtual machine. See the customization options in the file [`Vagrantfile`](https://github.com/mysociety/alaveteli/blob/master/Vagrantfile#L30) at the top level of the Alaveteli repository. + +The options can be set either by prefixing the vagrant command, or by +exporting to the environment. + + # Prefixing the command + $ ALAVETELI_VAGRANT_MEMORY=2048 vagrant up + + # Exporting to the environment + $ export ALAVETELI_VAGRANT_MEMORY=2048 + $ vagrant up + +Both have the same effect, but exporting will retain the variable for the duration of your shell session. + -- cgit v1.2.3 From b429da6a33c2e75756a26168c42435cf52f931de Mon Sep 17 00:00:00 2001 From: Louise Crow Date: Wed, 30 Jul 2014 09:38:41 +0100 Subject: Add next steps section. --- docs/installing/vagrant.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/installing/vagrant.md') diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index 65be1be51..8938d496b 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -48,8 +48,11 @@ Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. # in the virtual machine terminal bundle exec rails server +## What next? -# Customizing the Vagrant instance +Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). + +## Customizing the Vagrant instance The Vagrantfile allows customisation of some aspects of the virtual machine. See the customization options in the file [`Vagrantfile`](https://github.com/mysociety/alaveteli/blob/master/Vagrantfile#L30) at the top level of the Alaveteli repository. -- cgit v1.2.3 From 0c2596903c85ff9b51879b29ce948f5544412b7f Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Wed, 11 Feb 2015 11:54:28 +0000 Subject: update Vagrant page Specically I've needed to shut the server down on my Vagrant without having access to the terminal window that was running the server, and was troubled by the classic docs error of showing how to start something without also knowing how to stop it (driving instructors: show the brake pedal before showing the accelerator ;-) ) --- docs/installing/vagrant.md | 51 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 13 deletions(-) (limited to 'docs/installing/vagrant.md') diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index 8938d496b..e4b90584d 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -5,35 +5,38 @@ title: Vagrant # Alaveteli using Vagrant

-Vagrant provides an easy method to set up virtual development environments; for -further information see the Vagrant website. -We bundle an example Vagrantfile in the repository, which runs the -install script for you. + Vagrant provides an easy method to set + up virtual development environments We bundle an example Vagrantfile in the + repository, which runs the + install script for you.

Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). The included steps will use vagrant to create a development environment -where you can run the test suite, the development server and make +where you can run the test suite and the development server, and make changes to the codebase. -The basic process is to create a base virtual machine, and then +The basic process is to create a base virtual machine (VM), and then provision it with the software packages and setup needed. The supplied scripts will create you a Vagrant VM based on the server edition of Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. -1. Get a copy of Alaveteli from GitHub and create the Vagrant instance. - This will provision the system and can take some time - usually at - least 20 minutes. +1. Get a copy of Alaveteli from + GitHub: # on your machine $ git clone git@github.com:mysociety/alaveteli.git $ cd alaveteli $ git submodule update --init + +2. Create the Vagrant VM. This will provision the system and can take some time + — sometimes as long as 20 minutes. + $ vagrant --no-color up -2. You should now be able to ssh in to the Vagrant guest OS and run the - test suite: +3. You should now be able to log in to the Vagrant guest OS with `ssh` and run + the test suite: $ vagrant ssh @@ -42,12 +45,34 @@ Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. $ bundle exec rake spec -3. Run the rails server and visit the application in your host browser - at http://10.10.10.30:3000 +4. Run the rails server: # in the virtual machine terminal bundle exec rails server +You can now visit the application in your browser (on the same machine that is +running Vagrant) at `http://10.10.10.30:3000`. + +If you need to stop the server, simply press **Ctl-C** within that shell. + +It's also possible to stop the server from a different terminal shell in the +Vagrant VM. Log in, find the process ID for the Alaveteli server (in the example +below, this is `1234`), and issue the `kill` command: + + $ vagrant ssh + + # now in a terminal on the virtual machine + $ cat /home/vagrant/alaveteli/tmp/pids/server.pid + 1234 + $ kill -2 1234 + +Alternatively, you can stop down the whole VM without deleting it with the +command vagrant halt +on the host command line. To start it up again, go to step 2, above — it +won't take so long this time, because the files are already in place. +See [the Vagrant documentation](https://docs.vagrantup.com/v2/) +for full instructions on using Vagrant. + ## What next? Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). -- cgit v1.2.3 From 75a11d4d75246a7c07d684296250552e3a097614 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Wed, 11 Feb 2015 12:21:29 +0000 Subject: fix typo: shut down, not stop down --- docs/installing/vagrant.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/installing/vagrant.md') diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index e4b90584d..a0b058da5 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -66,7 +66,7 @@ below, this is `1234`), and issue the `kill` command: 1234 $ kill -2 1234 -Alternatively, you can stop down the whole VM without deleting it with the +Alternatively, you can shut down the whole VM without deleting it with the command vagrant halt on the host command line. To start it up again, go to step 2, above — it won't take so long this time, because the files are already in place. -- cgit v1.2.3