Skip to content

C
configuration
Commit f35584ea by John Jarvis
Options

updating readme and vagrant files

parent 545a0ae0
Showing with 4 additions and 291 deletions
vagrant/devstack/README.rst
......@@ -18,287 +18,5 @@ The ``devstack`` instance is designed to run code and tests, but you can do most
- You can load pages served by the running Vagrant instance.
Prerequisites
-------------
This guide assumes:
- You know how to open a terminal and use basic Linux operating system commands.
- You understand basic virtualization concepts and are familiar with `Vagrant`__
- You are familiar with `Django`__ development (for LMS and Studio)
- You are familiar with `Sinatra`__ development (for Forums)
__ http://docs.vagrantup.com/v2/
__ http://www.djangoproject.com/
__ http://www.sinatrarb.com/
Installation
------------
1. `Install Vagrant`__ (version 1.3.4 or higher)
2. Install the ``vagrant-hostsupdater`` plugin:
.. code:: bash
vagrant plugin install vagrant-hostsupdater
3. `Install Ansible`__ (version 1.3.2 or higher)
4. Clone the edX configuration repo:
.. code:: bash
git clone https://github.com/edx/configuration
5. From the ``configuration/vagrant/devstack`` directory, create the Vagrant instance. If you have never used Vagrant before, take a moment to read the `Why Vagrant?`__ page, which explains the Vagrant commands in detail.
.. code:: bash
vagrant up
A new Vagrant instance will be created, with requirements for these repositories installed:
- `edx-platform`__ (LMS and Studio)
- `cs_comments_service`__
The first time you create the instance, Vagrant will download the base box, which is about 2GB.
After downloading the base box, Vagrant will automatically provision your new virtual server using the Ansible scripts from this repo.
If you destroy and recreate the VM, Vagrant will re-use the box it downloaded.
__ http://docs.vagrantup.com/v2/installation/index.html
__ http://www.ansibleworks.com/docs/intro_installation.html
__ http://docs.vagrantup.com/v2/why-vagrant/index.html
__ https://github.com/edx/edx-platform
__ https://github.com/edx/cs_comments_service
Troubleshooting
---------------
Please refer to the `edx-platform wiki`__ for solutions to common issues.
__ https://github.com/edx/edx-platform/wiki/Simplified-install-with-vagrant#troubleshooting
Getting Started
---------------
In the ``configuration/vagrant/devstack`` directory, `ssh into the Vagrant instance`__:
.. code:: bash
vagrant ssh
This will log you in as the ``vagrant`` user. Within the Vagrant instance, you will be able to start services (LMS, Studio, and Forums) and run tests.
- The ``edx-platform`` repo (for LMS and Studio) is cloned to ``/edx/app/edxapp/edx-platform`` and synced with ``devstack/edx-platform`` on the host system.
- The ``cs_comments_service`` repo (for Forums) is cloned to ``/edx/app/forum/cs_comments_service`` and synced with ``devstack/cs_comments_service`` on the host system.
To start the services and run tests, you will need to log in as either the ``edxapp`` or ``forum`` user. See below for instructions.
__ http://docs.vagrantup.com/v2/getting-started/up.html
LMS Workflow
------------
1. Within the Vagrant instance, switch to the ``edxapp`` account:
.. code:: bash
sudo su edxapp
2. Compile Sass and CoffeeScript:
.. code:: bash
rake assets[lms,devstack]
3. Update Python requirements:
.. code:: bash
pip install -r requirements/edx/base.txt
4. Update the Ruby requirements:
.. code:: bash
bundle install
5. Start the LMS using `runserver`__:
.. code:: bash
./manage.py lms runserver --settings=devstack 0.0.0.0:8000
6. Open a browser on your host machine and navigate to ``localhost:8000`` to load the LMS. (Vagrant will forward port 8000 to the LMS server running in the VM.)
__ https://docs.djangoproject.com/en/dev/ref/django-admin/#runserver-port-or-address-port
Studio Workflow
---------------
1. Within the Vagrant instance, switch to the ``edxapp`` account:
.. code:: bash
sudo su edxapp
2. Compile Sass and CoffeeScript:
.. code:: bash
rake assets[cms,devstack]
3. Update Python requirements:
.. code:: bash
pip install -r requirements/edx/base.txt
4. Update the Ruby requirements:
.. code:: bash
bundle install
5. Start Studio using `runserver`__:
.. code:: bash
./manage.py cms runserver --settings=devstack 0.0.0.0:8001
6. Open a browser on your host machine and navigate to ``localhost:8001`` to load Studio. (Vagrant will forward port 8001 to the Studio server running in the VM.)
__ https://docs.djangoproject.com/en/dev/ref/django-admin/#runserver-port-or-address-port
Forum Workflow
--------------
1. Within the Vagrant instance, switch to the ``forum`` account:
.. code:: bash
sudo su forum
2. Update Ruby requirements:
.. code:: bash
bundle install
3. Start the server:
.. code:: bash
ruby app.rb
4. Access the API at ``localhost:4567`` (Vagrant will forward port 4567 to the Forum server running in the VM.)
Running LMS/Studio Tests
------------------------
1. Within the Vagrant instance, switch to the ``edxapp`` account:
.. code:: bash
sudo su edxapp
2. Run the Python unit tests:
.. code:: bash
rake test:python
3. Run the JavaScript unit tests:
.. code:: bash
rake test:js
4. Run the LMS and Studio acceptance tests:
.. code:: bash
rake test:acceptance
See `edx-platform testing documentation`__ for detailed information about writing and running tests.
__ https://github.com/edx/edx-platform/blob/master/docs/internal/testing.md
Enabling Asset Pipeline for LMS/Studio
--------------------------------------
By default, Django's ``runserver`` serves static assets (CSS and JavaScript) directly from the source files in the ``edx-platform`` repo. This allows you to make changes and quickly see the results.
In production, however, we process static assets using `django-pipeline`__ To verify that your changes will work in production, you can run LMS and Studio with the pipeline enabled:
1. Switch to the ``edxapp`` account:
.. code:: bash
sudo su edxapp
2. Gather static assets:
.. code:: bash
rake lms:gather_assets:devstack
rake cms:gather_assets:devstack
3. Start the server with ``--nostatic``:
.. code:: bash
# To start the LMS
./manage.py lms runserver --settings=devstack --nostatic 0.0.0.0:8000
# To start Studio
./manage.py cms runserver --settings=devstack --nostatic 0.0.0.0:8001
__ http://django-pipeline.readthedocs.org/en/latest/
Updating the Environment
------------------------
If system requirements change, you will need to update the Vagrant instance:
1. Checkout the release branch of the configuration repo:
.. code:: bash
git checkout release
git pull
2. From the ``configuration/vagrant/devstack`` directory, provision the Vagrant instance:
.. code:: bash
vagrant provision
This process will perform a ``git clean`` of the ``edx-platform`` and ``cs_comments_service`` repositories, so make sure that any changes you had are checked in or stashed.
Recreating the Environment
--------------------------
To destroy and recreate the environment:
.. code:: bash
vagrant destroy
vagrant up
This will perform a ``git clean`` of the ``edx-platform`` and ``cs_comments_service`` repositories. You will also lose any work stored in the Vagrant instance as that instance will be destroyed and a new one created from scratch.
Installation instructions - https://github.com/edx/configuration/wiki#installing-edx-using-a-pre-built-vagrant-devstack-image
Using the devstack - https://github.com/edx/configuration/wiki/Using-the-edX-devstack
vagrant/devstack/Vagrantfile
......@@ -5,19 +5,14 @@ Vagrant.configure("2") do |config|
# For efficiency, we create custom base box from an Ubuntu 12.04 image
# Once the custom base box is created, we use that as a starting point.
# config.vm.box = "precise64"
# config.vm.box_url = "http://files.vagrantup.com/precise64.box"
config.vm.box = "edx-devstack"
config.vm.box_url = "https://s3.amazonaws.com/vagrant.testeng.edx.org/edx-devstack.box"
config.vm.box = "precise64"
config.vm.box_url = "http://files.vagrantup.com/precise64.box"
config.vm.network :private_network, ip: "192.168.33.10"
config.vm.network :forwarded_port, guest: 8000, host: 8000
config.vm.network :forwarded_port, guest: 8001, host: 8001
config.vm.network :forwarded_port, guest: 4567, host: 4567
config.vm.synced_folder "edx-platform", "/edx/app/edxapp/edx-platform", :create => true, nfs: true
config.vm.synced_folder "cs_comments_service", "/edx/app/forum/cs_comments_service", :create => true, nfs: true
config.hostsupdater.aliases = ["preview.localhost"]
config.vm.provider :virtualbox do |vb|
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment