Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
New Open edX Install/Operations doc
This commit is contained in:
Mark Hoeber
2014-05-22 12:39:25 -04:00
parent 608eef2750 b2647dab43
commit afe306439f
11 changed files with 697 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
docs/en_us/install_operations/Makefile Normal file
View File

@@ -0,0 +1,183 @@
# 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."

0
docs/en_us/install_operations/__init__.py Normal file
View File

17
docs/en_us/install_operations/source/change_log.rst Normal file
View File

@@ -0,0 +1,17 @@
############
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`.

46
docs/en_us/install_operations/source/conf.py Normal file
View File

@@ -0,0 +1,46 @@
# -*- 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 = ''

139
docs/en_us/install_operations/source/devstack/install_devstack.rst Normal file
View File

@@ -0,0 +1,139 @@
.. 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

196
docs/en_us/install_operations/source/devstack/run_devstack.rst Normal file
View File

@@ -0,0 +1,196 @@
.. 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``.

9
docs/en_us/install_operations/source/devstack/test_devstack.rst Normal file
View File

@@ -0,0 +1,9 @@
.. include:: ../links.rst
.. _Testing on the edX Developer Stack:
####################################
Testing on the edX Developer Stack
####################################

19
docs/en_us/install_operations/source/index.rst Executable file
View File

@@ -0,0 +1,19 @@
.. 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

60
docs/en_us/install_operations/source/install_options.rst Normal file
View File

@@ -0,0 +1,60 @@
.. 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.

12
docs/en_us/install_operations/source/links.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _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

16
docs/en_us/install_operations/source/read_me.rst Normal file
View File

@@ -0,0 +1,16 @@
#########
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