Commit cf132023 authored by Maarten de Waard's avatar Maarten de Waard 🤘🏻
Browse files

initial commit

# Minimal makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXPROJ = Settingupedx
SOURCEDIR = _source
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
# -*- coding: utf-8 -*-
# Setting up edx documentation build configuration file, created by
# sphinx-quickstart on Thu Mar 2 17:27:41 2017.
# This file is execfile()d with the current directory set to its
# containing dir.
# Note that not all possible configuration values are present in this
# autogenerated file.
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.intersphinx',
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Setting up edx'
copyright = u'2017, Maarten de Waard'
author = u'Maarten de Waard'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# The short X.Y version.
version = u'0'
# The full version, including alpha/beta/rc tags.
release = u'0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# 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 = ['_static']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'Settingupedxdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
# Latex figure (float) alignment
# 'figure_align': 'htbp',
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Settingupedx.tex', u'Setting up edx Documentation',
u'Maarten de Waard', 'manual'),
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'settingupedx', u'Setting up edx Documentation',
[author], 1)
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Settingupedx', u'Setting up edx Documentation',
author, 'Settingupedx', 'One line description of project.',
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
# epub_identifier = ''
# A unique identification for the text.
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'': None}
.. Setting up edx documentation master file, created by sphinx-quickstart on Thu
Mar 2 17:27:41 2017. You can adapt this file completely to your liking, but it
should at least contain the root `toctree` directive.
Setting up Open EdX
.. toctree::
:maxdepth: 2
Initial machine setup
To recreate this machine:
1. Set the OPENEDX_RELEASE variable:
``export OPENEDX_RELEASE=open-release/ficus.1``
2. Bootstrap the Ansible installation:
``wget$OPENEDX_RELEASE/util/install/ -O - | sudo bash``
3. (Optional) If this is a new installation, randomize the passwords:
``wget$OPENEDX_RELEASE/util/install/ -O - | bash``
4. Install Open edX:
``wget$OPENEDX_RELEASE/util/install/ -O - | bash``
.. note:: You might have to re-run the last step because it somehow always
fails the first time on creating the swap file...
Please don't actually pipe to sudo bash, but check the scripts. Also don't try
to be a hero unless you are: you don't want to get lost in the clusterfuck of
EdX ansible scripts.
Installation instructions from:
It is possible to set variables like the platform's name in a ``.yml`` file. To
update these variables system-wide, you need to run an update script, that
recompiles all the assets, templates, configurations, etc. This is done by
running ``/edx/bin/update``. It requires you to specify a repository and a
branch or release. Since we installed ficus.1 in the installation steps and I'm
currently only focussing on the edx platform, I always run
``/edx/bin/update edx-platform open-release/ficus.1``.
Be careful with running this command. If anything fails, your system will enter
a broken state and anyone trying to access the platform will get mad at you.
The normal update script does not include the my-passwords.yml file you created
by running ``generate-passwords``, so be sure to include this in the
``server-vars.yml`` file by using the ``include_vars`` attribute:
Because you can't include files from vars files, it is impossible to include the
passwords file from there. Therefore I hacked the following rules into the
``/edx/bin/update`` script. Be sure to change ``/home/maarten/my-passwords.yml``
to a more sensible location...
.. code::
if [[ -f /home/maarten/my-passwords.yml ]]; then
echo "\n\nINCLUDING PASSWORDS!\n\n";
extra_args="${extra_args} -e@/home/maarten/my-passwords.yml"
.. note:: If your playbook fails at the step *TASK [edxapp : gather {{ item }}
static assets with paver]*, it is likely that your passwords file has not
been included. There will be *no* mention of this in the error, however... It
will just fail at a step that runs ````.
Adding Let's Encrypt TLS certificates
Install certbot and get a certificate for your Open EdX instance. Note that you
will probably have to include several CN's or get several certificates, for
example for the subdomains you have for studio, preview, etc. Find out where
Certbot places your certificates, and remember that location.
Next, we will add the certificate path to ``server-vars.yml`` so the update
script can place them in the correct location:
.. code::
# This one's optional, but recommended
NGINX_SSL_CERTIFICATE: < The absolute path to cert.pem >
NGINX_SSL_KEY: < The absolute path to privkey.pem >
Now, I had the problem that certbot uses symlinks to differently named files.
Because the nginx role copies the certificate from one place to another and uses
Jinja's ``basename`` attribute for the new name, my certificate was called
``cert1.pem`` (the name of the certificate in LE's archive) instead of
``cert.pem`` (the name of the symlink to the certificate in LE's live). This
results in error in the nginx configuration. I currently hotfixed this by
hardcoding the following in the nginx role (
.. code::
- name: copy ssl cert
dest: "/etc/ssl/certs/cert.pem"
owner: root
group: root
mode: 0644
when: ssl_cert.stat.exists and NGINX_ENABLE_SSL and NGINX_SSL_CERTIFICATE != 'ssl-cert-snakeoil.pem'
- install
- install:configuration
- name: copy ssl key
src: "{{ NGINX_SSL_KEY }}"
dest: "/etc/ssl/private/privkey.pem"
owner: root
group: root
mode: 0640
when: ssl_key.stat.exists and NGINX_ENABLE_SSL and NGINX_SSL_KEY != 'ssl-cert-snakeoil.key'
no_log: True
- install
- install:configuration
Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Supports Markdown
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