Commit 6fbfe941 authored by Kristina Hoeppner's avatar Kristina Hoeppner

Merge branch 'docker-build' into 'master'

Dockerize the manual build process

See merge request !5
parents 68da3203 c25374de
FROM debian:stable
ADD requirements.txt /tmp/requirements.txt
RUN set -o errexit -o nounset \
&& groupadd --system --gid $IMAGE_GID docbuilder \
&& useradd --system --gid docbuilder --uid $IMAGE_UID --shell /bin/bash --create-home docbuilder \
&& apt-get update \
&& apt-get install -y python3-pip make git bzr gettext rsync \
&& pip3 install -r /tmp/requirements.txt
USER docbuilder
# Create docbuilder/source volume
# We expect this to be volume mounted to supply the document source files
VOLUME "/home/docbuilder/source"
WORKDIR /home/docbuilder/source
RUN set -o errexit -o nounset \
&& mkdir -p /home/docbuilder/.ssh \
&& chown docbuilder:docbuilder /home/docbuilder/.ssh \
&& chmod 700 /home/docbuilder/.ssh \
&& echo "Testing sphinx installation" \
&& sphinx-build --version
The Mahara User Manual is written using [reStructuredText]( # Building Mahara docs
and built using [Sphinx](
The Mahara User Manual is:
Contributing to and building the documentation - written using [reStructuredText](
============================================== - built using [Sphinx](
- with a docker builder
To get started, use a Python virtual environment to install the stuff in `requirements.txt`.
You'll also need a fairly recent distribution of TeX Live in order to render PDFs properly.
Ubuntu 16.04 ships with TeX Live 2015 which includes XeTeX, which handles Unicode and
OpenType fonts properly, and the language metrics (hyphenation etc.) that Sphinx uses to
build translations.
Ubuntu 16.04 minimum packages for html doc build: # Quickstart
apt-get install python-virtualenv make git bzr gettext Run one of the commands below to build the docs. The first command only builds english.
The second builds all translations(and takes longer).
additional Ubuntu 16.04 packages required for pdf doc build: ```
docker run -v $(pwd)/:/home/docbuilder/source mahara/docbuilder TRANSLATIONS=en html
docker run -v $(pwd)/:/home/docbuilder/source mahara/docbuilder html
apt-get install texlive-xetex texlive-latex-recommended texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra The built docs will be in the `build/html` directory(on your host machine.
apt-get install texlive-lang-french texlive-lang-german texlive-lang-european
Clone this git repository, and in its directory, start the environemnt and install the ## Pre-requisites
virtualenv venv ### Docker docbuilder
. venv/bin/activate
pip install -r requirements.txt
Then you can build the documentation with the make command. Some common examples: [Docker]( needs to be available on your workstation.
make html # html for languages: en de fr nl If Docker is not already available it needs to be installed and configured before
make TRANSLATIONS=en html # html for en only you continue.
make TRANSLATIONS=en latexpdf # pdf for en only
Have a look at the If docker is available you can build the docbuilder image on Linux with:
[Hitchhiker's Guide to Python](
tutorial for more information about how to use Python virtual environments; Don't panic,
it's easy!
Deploying to a server that can't install remote packages ```
======================================================== cd manual-build
docker build --build-arg IMAGE_UID=`id -u` --build-arg IMAGE_UID=`id -g` --tag mahara/docbuilder .
To do this, make a wheelhouse (a directory of pre-compiled Python packages) and copy it over The `mahara/docbuilder` image is based on a debian docker image with additional
to your server, then on the server tell pip (in the virtual environment) to install them. packages that are required for building the docs installed. Using a docker image
for this makes it easy to get going with the same build environment as used by
For instance, on your workstation: The image is also made so that the default user has the same UID:GID as the current
system user. This is so that the built files are owned by the current user on the
host machine(otherwise they might be owned by root).
pip wheel -w /tmp/wheelhouse -r requirements.txt
rsync -avz /tmp/wheelhouse
And on the server:
cd /wherever/your/manual/is/installed
. venv/bin/activate
pip install --no-index --find-links=/tmp/wheelhouse
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