From 8dd10cbc8a2e90d1da84e207105b3209c9139a4b Mon Sep 17 00:00:00 2001 From: zador-blood-stained Date: Sat, 21 Apr 2018 13:47:06 +0300 Subject: [PATCH] Update Docker docs --- docs/Developer-Guide_Build-Preparation.md | 6 ++-- ...> Developer-Guide_Building-with-Docker.md} | 34 ++++++++++++++++--- mkdocs.yml | 1 + 3 files changed, 34 insertions(+), 7 deletions(-) rename docs/{Developer-Guide_Building_with_Docker.md => Developer-Guide_Building-with-Docker.md} (62%) diff --git a/docs/Developer-Guide_Build-Preparation.md b/docs/Developer-Guide_Build-Preparation.md index eab6f692..517b6eac 100644 --- a/docs/Developer-Guide_Build-Preparation.md +++ b/docs/Developer-Guide_Build-Preparation.md @@ -3,8 +3,8 @@ - x86/x64 machine running any OS; 4G ram, SSD, quad core (recommended), - [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or similar virtualization software **(highly recommended with a minimum of 20GB hard disk space for the virtual disk image)**, - Setting up VirtualBox and compile environment is easy following our [Vagrant tutorial](https://docs.armbian.com/Developer-Guide_Using-Vagrant/), -- when you don't want to build whole OS images (`KERNEL_ONLY=yes`) then [Docker](Developer-Guide_Building_with_Docker.md), [systemd-nspawn](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html) or other containerization software can be used, -- **Only supported** compilation environment is [Ubuntu Xenial 16.04 x64](http://archive.ubuntu.com/ubuntu/dists/xenial-updates/main/installer-amd64/current/images/netboot/mini.iso) (**no other releases are supported**! It has to be exactly 16.04 otherwise default compiler versions might not match so if you're on an older Ubuntu release upgrade to 16.04 now, if you use a newer Ubuntu version start with 16.04 from scratch), +- [Docker](Developer-Guide_Building-with-Docker.md) environment is also supported for building kernels and full OS images, +- **The only supported** compilation environment is [Ubuntu Xenial 16.04 x64](http://archive.ubuntu.com/ubuntu/dists/xenial-updates/main/installer-amd64/current/images/netboot/mini.iso) (**no other releases are supported**! It has to be exactly 16.04 otherwise default compiler versions might not match so if you're on an older Ubuntu release upgrade to 16.04 now, if you use a newer Ubuntu version start with 16.04 from scratch), - installed basic system, OpenSSH and Samba (optional), - no spaces in full path to the build script location allowed, - superuser rights (configured `sudo` or root shell). @@ -13,6 +13,8 @@ Please note that system requirements (both hardware and OS/software) may differ # How to start? +#### Native and Virtualbox environments: + Login as root and run: apt-get -y -qq install git diff --git a/docs/Developer-Guide_Building_with_Docker.md b/docs/Developer-Guide_Building-with-Docker.md similarity index 62% rename from docs/Developer-Guide_Building_with_Docker.md rename to docs/Developer-Guide_Building-with-Docker.md index a89d54cb..130bb958 100644 --- a/docs/Developer-Guide_Building_with_Docker.md +++ b/docs/Developer-Guide_Building-with-Docker.md @@ -1,12 +1,36 @@ -# Building Armbian using Red Hat or CentOS +# Officially supported and tested method for building with Docker -## How to build my own kernel? +This method works for building u-boot and kernel packages as well as building full OS images. +Building additional packages (`EXTERNAL_NEW`) is not supported. -First of all, it is important to notice that you will be able to build `kernel` and `uBoot`. The container method is not suitable for building full Armbian images (the full SD card image containing the userland packages). +## Requirements + +- x86/x64 Linux host that supports running a recent Docker daemon. Please refer to Docker documentation for details. +- Docker version 17.06 CE or newer. +- For launching the process as a non-root user this user needs to be added to the `docker` group. Please refer to Docker documentation for details. +- Enough free disk space on the storage used for Docker containers and named volumes. Named volumes path can be changed using standard Docker utilites, please refer to Docker documentation for details. + +## Details + +Build process should be started by running `./compile.sh docker` on the host. +The proces will create and run a Docker container with 2 named volumes `armbian-cache` and `armbian-ccache` and mount local diretories `output` and `userpatches`. +Additional command line arguments can be passed to `compile.sh` after `docker` like this: `./compile.sh docker KERNEL_ONLY=yes BOARD=cubietruck BRANCH=next KERNEL_CONFIGURE=yes`. +A configuration file named `config-docker-guest.conf` can be created to set default values for build options. Passing a custom config file name is currently not implemented. + + +# Creating and running Docker container manually + +NOTE: These methods are not supported by Armbian developers. Use them at your own risk. + +### Example: Building Armbian using Red Hat or CentOS + +Tested by [@rfrht](https://github.com/rfrht) + +First of all, it is important to notice that you will be able to build `kernel` and `u-boot` packages. The container method is not suitable for building full Armbian images (the full SD card image containing the userland packages). This setup procedure was validated to work with Red Hat Enterprise Linux 7. -### Preparing your build host +#### Preparing your build host In order to be able to run Docker containers, if you have not done so, just install the Docker package: @@ -30,7 +54,7 @@ And in order to not mistake the newly created `build` directory, I rename it to # mv build build-armbian # cd build-armbian -### Preparing the Container +#### Preparing the Container Docker will now check out the correct Ubuntu image to your build enviromnent and create a Docker **image** that will used as a template for your containers. This image template will be named `armbian_dev`: diff --git a/mkdocs.yml b/mkdocs.yml index 2a40f4be..391fbed4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ pages: - 'Developer Guide' : - 'Building Armbian' : 'Developer-Guide_Build-Preparation.md' - 'Building with Vagrant' : 'Developer-Guide_Using-Vagrant.md' + - 'Building with Docker': 'Developer-Guide_Building-with-Docker.md' - 'Build Options' : 'Developer-Guide_Build-Options.md' - 'User Configurations' : 'Developer-Guide_User-Configurations.md' - 'FEL boot' : 'Developer-Guide_FEL-boot.md'