Merge pull request #3592 from edx/markhoeber/documentation/doc-389

New Open edX Install/Operations doc

docs/en_us/install_operations/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+Q_FLAG        = 
+
+ifeq ($(quiet), true)
+Q_FLAG = -Q
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/getting_started.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/getting_started.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/getting_started"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/getting_started"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/en_us/install_operations/source/change_log.rst

+############
+Change Log
+############
+
+************
+May, 2014
+************
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 05/21/2014
+     - The initial release of this guide, with the sections :ref:`Installing the edX Developer Stack` and :ref:`Running the edX Developer Stack`.
+   
\ No newline at end of file

docs/en_us/install_operations/source/conf.py

+# -*- coding: utf-8 -*-
+#
+
+import sys, os
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+
+
+
+
+
+
+
+sys.path.append(os.path.abspath('../../../'))
+sys.path.append(os.path.abspath('../../'))
+
+#from docs.shared.conf import *
+
+sys.path.insert(0, os.path.abspath('.'))
+
+master_doc = 'index'
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path.append('source/_templates')
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path.append('source/_static')
+
+
+# General information about the project.
+project = u'Installing, Configuring, and Running the edX Platform'
+copyright = u'2014, edX'
+
+# The short X.Y version.
+version = ''
+# The full version, including alpha/beta/rc tags.
+release = ''

docs/en_us/install_operations/source/devstack/install_devstack.rst

+.. include:: ../links.rst
+
+.. _Installing the edX Developer Stack:
+
+####################################
+Installing the edX Developer Stack
+####################################
+
+This chapter is intended for those who are installing and running the edX Developer Stack.
+
+See the following sections:
+
+* `Overview`_
+* `Components`_
+* `Knowledge Prerequisites`_
+* `Software Prerequisites`_
+* `Install DevStack`_
+* `Install DevStack using the Torrent file`_
+
+
+**********
+Overview
+**********
+
+The edX Developer Stack, known as **Devstack**, is a Vagrant instance designed
+for local development.
+
+Devstack:
+
+* Uses the same system requirements as production. This allows you to
+  discover and fix system configuration issues early in development.
+
+* Simplifies certain production settings to make development more convenient.
+  For example, `nginx`_ and `gunicorn`_ are disabled in Devstack; Devstack uses
+  Django's runserver instead.
+
+
+********************
+Components
+********************
+
+Devstack includes the following edX components:
+
+* The Learning Management System (LMS)
+* edX Studio
+* Discussion Forums
+* Open Response Assessor (ORA)
+  
+
+**************************
+Knowledge Prerequisites
+**************************
+
+To use Devstack, you should:
+
+* Understand basic terminal usage. If you are using a Mac computer, see
+  `Introduction to the Mac OS X Command Line`_. If you are using a Windows
+  computer, see `Windows Command Line Reference`_.
+
+* Understand Vagrant commands. See the `Vagrant Getting Started`_ guide for more
+  information.
+
+
+**************************
+Software Prerequisites
+**************************
+
+To install and run Devstack, you must first install:
+
+* `VirtualBox`_ 4.3.10 or higher
+
+* `Vagrant`_ 1.5.3 or higher
+
+* An NFS client, if your operating system does not include one. Devstack uses
+  VirtualBox Guest Editions to share folders through NFS.
+  
+
+**************************
+Install DevStack
+**************************
+
+To install Devstack directly from the command line, follow the instructions
+below. You can also install DevStack using a Torrent file, as explained in the
+next section.
+
+Before beginning the installation, ensure that you have your local computer's administrator's password.
+
+#. Ensure the NFSD client is running.
+
+#. Create the ``devstack`` directory and navigate to it in the command prompt.
+   
+   .. code-block:: bash
+
+     mkdir devstack
+     cd devstack
+
+#. Download the Devstack Vagrant file.
+   
+   .. code-block:: bash
+
+     curl -L https://raw.github.com/edx/configuration/master/vagrant/release/devstack/Vagrantfile > Vagrantfile
+
+#. Install the Vagrant vbguest plugin.
+   
+   .. code-block:: bash
+
+     vagrant plugin install vagrant-vbguest
+
+#. Create the Devstack virtual machine.
+
+   .. code-block:: bash
+
+     vagrant up
+
+   The first time you create the Devstack virtual machine, Vagrant downloads the
+   base box, which is about 4GB. If you destroy and recreate the virtual
+   machine, Vagrant re-uses the box it downloaded.
+
+#. When prompted, enter your local computer's administrator's password.
+   
+   Your password is needed so that NFS can be set up to allow users to access
+   code directories directly from your computer.
+
+When you have completed these steps, see :ref:`Running the edX Developer Stack`
+to begin using Devstack.
+
+
+*****************************************
+Install Devstack using the Torrent file
+*****************************************
+
+#. Download the Devstack `Torrent`_ file. 
+
+#. When you have the file on your computer, add the Virtual machine using the
+   command:
+
+    .. code-block:: bash
+  
+     vagrant box add box-name path-to-box-file

docs/en_us/install_operations/source/devstack/run_devstack.rst

+.. include:: ../links.rst
+
+.. _Running the edX Developer Stack:
+
+####################################
+Running the edX Developer Stack
+####################################
+
+See the following sections:
+
+* `Connect to the Devstack Virtual Machine`_
+* `Set Up Ability to Preview Units (Mac/Linux Only)`_
+* `Customize the Source Code Location`_
+* `Run the LMS on Devstack`_
+* `Run Studio on Devstack`_
+* `Run Discussion Forums on Devstack`_
+* `Default Accounts on Devstack`_
+
+
+****************************************
+Connect to the Devstack Virtual Machine
+****************************************
+
+#. To connect to the Devstack virtual machine, use the SSH command from the
+   `devstack` directory.
+
+  .. code-block:: bash
+
+   vagrant ssh
+
+2. To use Devstack and perform any of the tasks described in this section, you
+   must connect as the user **edxapp**.
+
+   .. code-block:: bash
+
+    sudo su edxapp
+
+   This command loads the edxapp environment from the file
+   ``/edx/app/edxapp/edxapp_env``. This puts ``venv python``, ``rbenv ruby`` and
+   ``rake`` are in your search path.
+
+   This command also sets the current working directory to the edx-platform
+   repository (``/edx/app/edxapp/edx-platform``).
+
+
+****************************************************
+Set Up Ability to Preview Units (Mac/Linux Only)
+****************************************************
+
+If you are installing Devstack on a Linux or Macintosh computer, in order to use
+the preview feature in edX Studio, you must add the following line to the
+``etc/hosts`` file:
+
+  .. code-block:: bash
+
+    192.168.33.10 preview.localhost
+
+
+************************************
+Customize the Source Code Location
+************************************
+
+You can customize the location of the edX source code that gets cloned when you
+provision Devstack. You may want to do this to have Devstack work with source
+code that already exists on your computer.
+
+By default, the source code location is the directory in which you run ``vagrant
+up``.  To change this location, set the ``VAGRANT_MOUNT_BASE`` environment
+variable to set the base directory for the edx-platform and cs_comments_service
+source code directories.
+
+.. WHERE IS VARIABLE?
+
+************************************
+Run the LMS on Devstack
+************************************
+
+When you run the LMS on Devstack, the command updates requirements and
+compiles assets, unless you use the ``fast`` option.
+
+The command uses the file ``lms/envs/devstack.py``. This file
+overrides production settings for the LMS.
+
+To run the LMS on Devstack:
+
+#. `Connect to the Devstack Virtual Machine`_.
+#. Run the following command:
+   
+   .. code-block:: bash
+
+    paver devstack lms
+
+   Or, to start the LMS without updating requirements and compiling assets, use the ``fast`` option:
+   
+   .. code-block:: bash
+
+    paver devstack --fast lms 
+
+   The LMS starts. 
+
+#. Open the LMS in your browser at ``http://localhost:8000/``. 
+
+   Vagrant forwards port 8000 to the LMS server running in the virtual machine.
+
+
+************************************
+Run Studio on Devstack
+************************************
+
+When you run Studio on Devstack, the command updates requirements and compiles
+assets, unless you use the ``fast`` option.
+
+You run Studio on Devstack with the file ``cms/envs/devstack.py``. This file
+overrides production settings for Studio.
+
+To run Studio on Devstack:
+
+#. `Connect to the Devstack Virtual Machine`_.
+#. Run the following command:
+   
+   .. code-block:: bash
+
+    paver devstack studio
+
+   Or, to start Studio without updating requirements and compiling assets, use
+   the ``fast`` option:
+   
+   .. code-block:: bash
+
+    paver devstack --fast studio 
+
+   Studio starts. 
+
+#. Open the LMS in your browser at ``http://localhost:8001/``. 
+ 
+   Vagrant forwards port 8001 to the Studio server running in the virtual
+   machine.
+
+************************************
+Run Discussion Forums on Devstack
+************************************
+
+To run discussion forums on Devstack:
+
+#. `Connect to the Devstack Virtual Machine`_.
+#. Switch to the discussion forum account:
+   
+   .. code-block:: bash
+
+    sudo su forum
+
+#. Update Ruby requirements. 
+
+   .. code-block:: bash
+
+    bundle install
+
+   .. note:: 
+     If you get a message for entering a password to install the bundled
+     RubyGems to the system, you can safely exit by entering ``control+c`` on a
+     Macintosh or ``Ctrl+C`` on Windows. The RubyGems will still be installed
+     correctly for the forum user.
+
+#. Start the discussion forums server.
+   
+   .. code-block:: bash
+
+    ruby app.rb -p 18080
+
+The discussions forum server starts. You can access the discussion forums API at
+``http://localhost:18080/``.
+
+************************************
+Default Accounts on Devstack
+************************************
+
+When you install Devstack, the following accounts are created:
+
+  .. list-table::
+   :widths: 20 60
+   :header-rows: 1
+
+   * - Account
+     - Description
+   * - staff@example.com
+     - An LMS and Studio user with course creation and editing permissions. This
+       user is a course staff member with rights to work with the demonstration
+       course in Studio.
+   * - verified@example.com
+     - A student account that you can use to access the LMS for testing verified certificates.
+   * - audit@example.com
+     - A student account that you can use the access the LMS for testing course auditing.
+   * - honor@example.com
+     - A student account that you can use the access the LMS for testing honor code certificates.
+
+The password for all of these accounts is ``edx``.

docs/en_us/install_operations/source/devstack/test_devstack.rst

+.. include:: ../links.rst
+
+
+.. _Testing on the edX Developer Stack:
+
+####################################
+Testing on the edX Developer Stack
+####################################
+

docs/en_us/install_operations/source/index.rst

+.. Getting_Started documentation master file, created by
+   sphinx-quickstart on Tue Apr 16 11:19:12 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+######################################################
+Installing, Configuring, and Running the edX Platform
+######################################################
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   read_me
+   change_log
+   install_options
+   devstack/install_devstack
+   devstack/run_devstack
+..   devstack/test_devstack
\ No newline at end of file

docs/en_us/install_operations/source/install_options.rst

+.. include:: links.rst
+
+########################################
+Open edX Platform Installation Options
+########################################
+
+You can install the Open edX Platform in one of the following three ways.
+
+**********
+Devstack
+**********
+
+The edX Developer Stack, known as **Devstack**, is a Vagrant instance designed
+for local development.
+
+Devstack is in the `edx configuration repository`_ on GitHub.
+
+This guide includes the following sections about Devstack:
+
+* :ref:`Installing the edX Developer Stack`
+
+* :ref:`Running the edX Developer Stack`
+  
+Additional sections are planned for future versions of this guide.
+
+See the `edx configuration repository wiki`_ for information from
+edX and the Open edX community about Devstack and other installation and
+configuration options. This wiki contains two pages with more information about Devstack:
+
+* `Devstack wiki`_
+* `Developing on Devstack`_
+
+
+**********
+Fullstack
+**********
+
+The edX Production Stack, known as **Fullstack**, is a Vagrant instance designed
+to set up all edX services on a single server in a production-like
+configuration.
+1
+Fullstack is in the `edx configuration repository`_ on GitHub.
+  
+Fullstack information is planned for future versions of this guide.
+
+You can see the `edx configuration repository wiki`_ for information from edX
+and the Open edX community on Fullstack and other installation and configuration options.
+
+
+==================
+Ubuntu 12.04 64 
+==================
+
+You can install the edX Production Stack on a single Ubuntu 12.04 64-bit server.
+
+Ubuntu information is planned for future versions of this guide.
+
+You can see the `edx configuration repository wiki`_ for information from edX
+and the Open edX community about Ubuntu and other installation and configuration
+options.
\ No newline at end of file

docs/en_us/install_operations/source/links.rst

+.. _nginx: http://nginx.com
+.. _gunicorn: http://gunicorn.org
+.. _Introduction to the Mac OS X Command Line: http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line
+.. _Windows Command Line Reference: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/ntcmds.mspx?mfr=true
+.. _Vagrant Getting Started: http://docs.vagrantup.com/v2/getting-started/index.html
+.. _VirtualBox: https://www.virtualbox.org/wiki/Downloads
+.. _Vagrant: http://www.vagrantup.com/downloads.html
+.. _Torrent: https://s3.amazonaws.com/edx-static/vagrant-images/20140418-injera-devstack.box?torrent
+.. _edx configuration repository: https://github.com/edx/configuration
+.. _edx configuration repository wiki: https://github.com/edx/configuration/wiki
+.. _Devstack wiki: https://github.com/edx/configuration/wiki/edX-Developer-Stack
+.. _Developing on Devstack: https://github.com/edx/edx-platform/wiki/Developing-on-the-edX-Developer-Stack
\ No newline at end of file

docs/en_us/install_operations/source/read_me.rst

+#########
+Read Me
+#########
+
+The edX *Installing and Configuring the edX Platform* documentation is created
+using RST_ files and Sphinx_. You, the user community, can help update and revise this documentation project on GitHub:
+
+  https://github.com/edx/edx-platform/tree/master/docs/install_operations/source
+
+To suggest a revision, fork the project, make changes in your fork, and submit
+a pull request back to the original project: this is known as the `GitHub Flow`_.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _LaTeX: http://www.latex-project.org/
+.. _`GitHub Flow`: https://github.com/blog/1557-github-flow-in-the-browser
+.. _RST: http://docutils.sourceforge.net/rst.html
\ No newline at end of file