build-vyos: rewrite documentation for building ISO

- Improve Docker build instructions
- Make clear that build from source is possible
- Add information about building from source
- Correct references to current branch with master branch

1 files changed, 111 insertions, 41 deletions

diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst
index 2ceaeda8..1ec9ffba 100644
--- a/docs/contributing/build-vyos.rst
+++ b/docs/contributing/build-vyos.rst
@@ -3,30 +3,45 @@
 Building VyOS
 =============
 
-This will guide you though the process of building a VyOS ISO using
-Docker_.  This process has been tested on clean installs of Debian Jessie, Stretch, and Buster. 
+There are different ways you can build VyOS.
+
+Building using a :ref:`Docker<build docker>` container, although not the only way, is the
+easiest way as all dependencies are managed for you. It also allows you to
+build ARM images on a x86 host.
+
+However, you can also set up your own build machine and :ref:`build from source<build source>`.
 
 .. note:: Starting with VyOS 1.2 the release model of VyOS has changed. 
    VyOS is now **free as in speech, but not as in beer**. This means
    that while VyOS is still an open source project, the release ISOs are no
-   longer free and can only be obtained via subscription, or by contributing to
-   the community. 
+   longer free and can only be obtained via subscription, or by contributing
+   to the community. 
    
    The source code remains public and an ISO can be built
    using the process outlined here.
 
+.. _build docker:
+
+Docker
+------
+
+This will guide you though the process of building a VyOS ISO using
+Docker_. This process has been tested on clean installs of Debian
+Jessie, Stretch, and Buster.
+
 Installing Docker_ and prerequisites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: none
 
-  $ apt-get update
-  $ apt-get install -y apt-transport-https ca-certificates curl \
-        gnupg2 software-properties-common
+  $ sudo apt-get update
+  $ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg2 \
+        software-properties-common
   $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
-  $ add-apt-repository "deb [arch=amd64] \
+  $ sudo add-apt-repository "deb [arch=amd64] \
         https://download.docker.com/linux/debian $(lsb_release -cs) stable"
-  $ apt-get update
-  $ apt-get install -y docker-ce
+  $ sudo apt-get update
+  $ sudo apt-get install -y docker-ce
 
 To be able to use Docker_, the current non-root user should be added to the
 ``docker`` group by calling: ``usermod -aG docker yourusername``
@@ -37,53 +52,111 @@ To be able to use Docker_, the current non-root user should be added to the
           on SMB or NFS shares will result in the container failing to build properly!
 
 
-Generating the container
-------------------------
+Build Docker Container
+^^^^^^^^^^^^^^^^^^^^^^
 
 The container can built by hand or by fetching the pre-built one from
-DockerHub. Using the pre-built VyOS DockerHub organisation (https://hub.docker.com/u/vyos) will
-ensure that the container is always up-to-date. A rebuild is triggered once the
-container changes (please note this will take 2-3 hours after pushing to
-the vyos-build repository).
+DockerHub. Using the pre-built containers from the `VyOS DockerHub organisation`_
+will ensure that the container is always up-to-date. A rebuild is triggered
+once the container changes (please note this will take 2-3 hours after pushing
+to the vyos-build repository).
 
-The container can always be built directly from source:
+.. note: If you are using the pre-built container, it will be automatically
+   downloaded from DockerHub if it is not found on your local machine when
+   you build the ISO.
+
+To manually download the container, run:
 
 .. code-block:: none
 
-  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build
-  $ docker build -t vyos/vyos-build docker
+  $ docker pull vyos/vyos-build:crux
+
+The container can always be built directly from source:
+
+.. code-block:: none
 
-.. note: The container is automatically downloaded from Dockerhub if it is not
-   found on your local machine when the below command is executed.
+  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
+  $ git clone -b master --single-branch https://github.com/vyos/vyos-build # For rolling release
+  $ cd vyos-build
+  $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2
+  $ docker build -t vyos/vyos-build docker # For rolling release
 
-.. note: We require one container per build branch, this means that the used
-   container in ``crux`` and ``current`` can and will differ once VyOS makes the 
+.. Note: We require one container per build branch, this means that the used
+   container in ``crux`` and ``master`` can and will differ once VyOS makes the 
    move towards Debian (10) Buster.
 
 
-Build ISO inside container
---------------------------
+Build ISO
+^^^^^^^^^
+
+If you have not build your own Docker image, you need to clone the repository to your local machine:
+
+.. code-block:: none
+
+  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
+  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For rolling release
 
-After the container is generated either manually or fetched from DockerHub,
-a fresh build of the VyOS ISO can begin.
+Now a fresh build of the VyOS ISO can begin. Change directory to the ``vyos-build`` directory and run:
 
 .. code-block:: none
 
-  $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash
+  $ cd vyos-build
+  $ docker run --rm -it --privileged -v $(pwd)/vyos-build:/vyos -w /vyos vyos/vyos-build:crux bash # For VyOS 1.2
+  $ docker run --rm -it --privileged -v $(pwd)/vyos-build:/vyos -w /vyos vyos/vyos-build bash # For rolling release
   vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 \
                                --build-by "your@email.tld" \
                                --build-type release --version 1.2.0
   vyos_bld@d4220bb519a0:/vyos# sudo make iso
 
-To select the container you want to run, you need to specify the branch you are
-interested in, this can be easily done by selecting the appropriate container
-image:
+The successfully built ISO should now be in the ``build/`` directory as
+``live-image-[architecture].hybrid.iso``.
+
+Good luck!
+
+.. note: Make sure to choose the matching container for the version of VyOS
+   that is being built, ``vyos/vyos-build:crux`` for VyOS 1.2 (crux) and 
+   ``vyos/vyos-build`` for rolling release.
 
-* For VyOS 1.2 (crux) use ``vyos/vyos-build:crux``
-* For our VyOS rolling release you should use ``vyos/vyos-build`` which will
-  always refer to the latest image.
+.. _build source:
 
-This ISO can be customized with the following list of configure options. 
+From source
+-----------
+
+To build from source, you will need:
+
+- Debian Buster for VyOS 1.2
+- Debian Stretch for the rolling releases
+
+To start, clone the repository to your local machine:
+
+.. code-block:: none
+
+  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
+  $ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For rolling release
+
+For the packages required, you can refer to the ``docker/Dockerfile`` file
+in the repository_. The ``./configure`` script will also warn you if any
+dependencies are missing.
+
+Once you have the required dependencies, you may configure the build by
+running ``./configure`` with your options. For details, refer to
+:ref:`Customizing the build<customize>`.
+
+Once you have configured your build, build the ISO by running:
+
+.. code-block:: none
+
+  $ sudo make iso
+
+The successfully built ISO should now be in the ``build/`` directory as
+``live-image-[architecture].hybrid.iso``.
+
+.. _customize:
+
+Customizing the build
+---------------------
+
+The build can be customized with the following list of configure options. 
 The full and current list can be generated with ``./configure --help``:
 
 .. code-block:: none
@@ -111,11 +184,8 @@ The full and current list can be generated with ``./configure --help``:
   --custom-apt-key CUSTOM_APT_KEY
                         Custom APT key file
 
-The successfully built ISO should now be in the `build/` directory. 
-
-Good luck!
+.. _Docker: https://www.docker.com
 
-.. note: The build process does not differentiate when building a ``crux`` ISO or ``rolling``
-   image. Make sure to choose the matching container for the version of VyOS that is being built.
+.. _VyOS DockerHub organisation: https://hub.docker.com/u/vyos
 
-.. _Docker: https://www.docker.com
+.. _repository: https://github.com/vyos/vyos-build