summaryrefslogtreecommitdiff
path: root/docs/contributing/build-vyos.rst
diff options
context:
space:
mode:
authorAndrew Ying <hi@andrewying.com>2020-07-17 13:25:30 +0100
committerAndrew Ying <hi@andrewying.com>2020-07-18 22:10:12 +0100
commit60008359c4631333f45102a46e39fd9a74ee4943 (patch)
treee0d46d7ca726392983065c8572bb4994a177ece0 /docs/contributing/build-vyos.rst
parent3419ccb9df462ef1323c23bcccb37c11217e1af2 (diff)
downloadvyos-documentation-60008359c4631333f45102a46e39fd9a74ee4943.tar.gz
vyos-documentation-60008359c4631333f45102a46e39fd9a74ee4943.zip
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
Diffstat (limited to 'docs/contributing/build-vyos.rst')
-rw-r--r--docs/contributing/build-vyos.rst152
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