diff options
author | Andrew Ying <hi@andrewying.com> | 2020-07-17 13:25:30 +0100 |
---|---|---|
committer | Andrew Ying <hi@andrewying.com> | 2020-07-18 22:10:12 +0100 |
commit | 60008359c4631333f45102a46e39fd9a74ee4943 (patch) | |
tree | e0d46d7ca726392983065c8572bb4994a177ece0 /docs/contributing/build-vyos.rst | |
parent | 3419ccb9df462ef1323c23bcccb37c11217e1af2 (diff) | |
download | vyos-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.rst | 152 |
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 |