From fed961fe02ce4634959185093781887f94b05e27 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:30:45 +0000 Subject: [PATCH 01/11] docs: Add missing distros to dev guide Added references to instal guides for CentOS, SLES, and Clear Linux. Also changed wording slightly given that some install guides (CentOS and SLES) install some components from source. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index f26ea892..f06b67ef 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -11,12 +11,15 @@ The recommended way to create a development environment is to first install the packaged versions of the Clear Containers components to create a working system: + * [CentOS*](centos-installation-guide.md) + * [Clear Linux*](clearlinux-installation-guide.md) * [Fedora*](fedora-installation-guide.md) + * [SLES*](sles-installation-guide.md) * [Ubuntu*](ubuntu-installation-guide.md) -The installation guide instructions will install all packaged -components, plus docker, the hypervisor and the Clear Containers image -and kernel. +The installation guide instructions will install all required Clear Containers +components, plus Docker*, the hypervisor, and the Clear Containers image and +kernel. ## Requirements to build individual components From fbfb327e1b459ad1417689f600b12b610961d2b3 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:32:14 +0000 Subject: [PATCH 02/11] docs: Add brackets and periods to dev guide Added missing periods and brackets for build requirements to make build requirements section clearer. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index f06b67ef..f75c4409 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -23,10 +23,10 @@ kernel. ## Requirements to build individual components - * [go 1.8.3](https://golang.org/) + * [go 1.8.3](https://golang.org/). * [gcc](https://gcc.gnu.org/) and associated C language build tooling - such as `make`, `autoconf` and `libtool` which are required - to build `cc-shim` + (e.g. `make`, `autoconf` and `libtool`) are required + to build `cc-shim`. ## Clear Containers 3.0 components From ed867e8f59f601b328cc4b86ac3a162052231a0a Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:33:16 +0000 Subject: [PATCH 03/11] docs: Render variables correctly in dev guide `GOPATH` is a variable so needs to be rendered in a fixed-width font in the dev guide. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index f75c4409..c8da65a1 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -45,13 +45,13 @@ See [the upgrading document](upgrading.md) for further details. ### Setup the environment -1. Define GOPATH +1. Define `GOPATH` ```bash $ export GOPATH=$HOME/go ``` -2. Create GOPATH Directory +2. Create `GOPATH` Directory ```bash $ mkdir -p $GOPATH From 47dd0419e13325ae2c9eb1b142f9f9ae32c84469 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:34:12 +0000 Subject: [PATCH 04/11] docs: Explain install will overwrite binaries in dev guide Added notes to the proxy and shim sections in the dev guide explaining that the `make install` will overwrite the package-installed binaries. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index c8da65a1..c1a6a642 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -78,6 +78,9 @@ See [the upgrading document](upgrading.md) for further details. $ sudo make install ``` + Note: the previous install step will overwrite any proxy binary installed from + the `cc-proxy` package. + 2. Shim ```bash @@ -87,6 +90,9 @@ See [the upgrading document](upgrading.md) for further details. $ sudo make install ``` + Note: the previous install step will overwrite any shim binary installed from + the `cc-shim` package. + 3. Runtime ```bash From 22d4bb1b9a78d0bd6f8d1252f5ebd4009baa42d5 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:36:50 +0000 Subject: [PATCH 05/11] docs: Move note to correct section of dev guide Move the note about the runtime build system back to the runtime section in the dev guide. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index c1a6a642..28b97b07 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -101,6 +101,12 @@ See [the upgrading document](upgrading.md) for further details. $ sudo -E PATH=$PATH make install-cc-system ``` + For more details on the runtime's build system, run: + + ```bash + $ make help + ``` + 4. Agent ```bash @@ -136,12 +142,6 @@ See [the upgrading document](upgrading.md) for further details. /usr/share/defaults/clear-containers/configuration.toml ``` -For more details on the runtime's build system, run: - -```bash -$ make help -``` - 5. Kernel The latest kernel for Clear Linux can be found on From 7ed1a843bb9d8566e707876cfed8dcca2e0d0efa Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:38:59 +0000 Subject: [PATCH 06/11] docs: Explain how to reconfigure Docker in dev guide Added details on how to reconfigure Docker to use a development version of the runtime in the dev guide. Fixes #892. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index 28b97b07..e7111551 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -101,6 +101,17 @@ See [the upgrading document](upgrading.md) for further details. $ sudo -E PATH=$PATH make install-cc-system ``` + The previous install step will create `/usr/local/bin/cc-runtime`. This + ensures the packaged version of the runtime from the `cc-runtime` package is + not overwritten. However, since the installation guide configured Docker to + call the runtime as `/usr/bin/cc-runtime`, it is necessary to modify the + docker configuration to make use of your newly-installed development runtime + binary: + + ```bash + $ sudo sed -i 's!cc-runtime=/usr/bin/cc-runtime!cc-runtime=/usr/local/bin/cc-runtime!g' /etc/systemd/system/docker.service.d/clear-containers.conf + ``` + For more details on the runtime's build system, run: ```bash From a582502b0aa779b4a6ed9abb22797945808b9b45 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:43:53 +0000 Subject: [PATCH 07/11] docs: Added packaging repo ref to dev guide Added a link to the packaging repository in the dev guide as it could be a useful resource. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index e7111551..c3fe7612 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -189,4 +189,8 @@ See [the upgrading document](upgrading.md) for further details. * [General Debugging](../README.md#debugging) * [Debugging the agent inside the hypervisor](debug-agent.md) * [Debugging the kernel inside the hypervisor](https://github.com/clearcontainers/runtime/blob/master/docs/debug-kernel.md) - + * Packaging + The repository used to create the packaged versions of Clear Containers + components for various Linux distributions is: + * https://github.com/clearcontainers/packaging + From b165e896dbf68b7663d96dbf1ec6e84e32377351 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:48:38 +0000 Subject: [PATCH 08/11] docs: Add TOC to dev guide Add a table of contents to the development guide. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index c3fe7612..b658c3f2 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -1,5 +1,12 @@ # Developers Clear Containers 3.0 Install +* [Initial setup](#initial-setup) +* [Requirements to build individual components](#requirements-to-build-individual-components) +* [Clear Containers 3.0 components](#clear-containers-3.0-components) + * [Setup the environment](#setup-the-environment) + * [Build and install components](#build-and-install-components) +* [See Also](#see-also) + This guide is not intended for end-users. Instead, this guide provides instructions for any developers eager to try Clear Containers 3.0 and who want to build Clear Containers from the source code and are familiar with the From 1a1b75084f1e145f15f5e9001064d9fc3f6f5568 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:53:41 +0000 Subject: [PATCH 09/11] docs: Create extra sections in dev guide Created new sections for each component and added them to the table of contents. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 173 ++++++++++---------- 1 file changed, 89 insertions(+), 84 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index b658c3f2..7ba1e59a 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -5,6 +5,11 @@ * [Clear Containers 3.0 components](#clear-containers-3.0-components) * [Setup the environment](#setup-the-environment) * [Build and install components](#build-and-install-components) + * [Proxy](#proxy) + * [Shim](#shim) + * [Runtime](#runtime) + * [Agent](#agent) + * [Kernel](#kernel) * [See Also](#see-also) This guide is not intended for end-users. Instead, this guide provides @@ -77,119 +82,119 @@ See [the upgrading document](upgrading.md) for further details. ### Build and install components -1. Proxy +#### Proxy - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/proxy - $ make - $ sudo make install - ``` +```bash +$ cd $GOPATH/src/github.com/clearcontainers/proxy +$ make +$ sudo make install +``` - Note: the previous install step will overwrite any proxy binary installed from - the `cc-proxy` package. +Note: the previous install step will overwrite any proxy binary installed from +the `cc-proxy` package. -2. Shim +#### Shim - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/shim - $ ./autogen.sh - $ make - $ sudo make install - ``` +```bash +$ cd $GOPATH/src/github.com/clearcontainers/shim +$ ./autogen.sh +$ make +$ sudo make install +``` - Note: the previous install step will overwrite any shim binary installed from - the `cc-shim` package. +Note: the previous install step will overwrite any shim binary installed from +the `cc-shim` package. -3. Runtime +#### Runtime - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/runtime - $ make build-cc-system - $ sudo -E PATH=$PATH make install-cc-system - ``` +```bash +$ cd $GOPATH/src/github.com/clearcontainers/runtime +$ make build-cc-system +$ sudo -E PATH=$PATH make install-cc-system +``` - The previous install step will create `/usr/local/bin/cc-runtime`. This - ensures the packaged version of the runtime from the `cc-runtime` package is - not overwritten. However, since the installation guide configured Docker to - call the runtime as `/usr/bin/cc-runtime`, it is necessary to modify the - docker configuration to make use of your newly-installed development runtime - binary: +The previous install step will create `/usr/local/bin/cc-runtime`. This +ensures the packaged version of the runtime from the `cc-runtime` package is +not overwritten. However, since the installation guide configured Docker to +call the runtime as `/usr/bin/cc-runtime`, it is necessary to modify the +docker configuration to make use of your newly-installed development runtime +binary: - ```bash - $ sudo sed -i 's!cc-runtime=/usr/bin/cc-runtime!cc-runtime=/usr/local/bin/cc-runtime!g' /etc/systemd/system/docker.service.d/clear-containers.conf - ``` +```bash +$ sudo sed -i 's!cc-runtime=/usr/bin/cc-runtime!cc-runtime=/usr/local/bin/cc-runtime!g' /etc/systemd/system/docker.service.d/clear-containers.conf +``` - For more details on the runtime's build system, run: +For more details on the runtime's build system, run: - ```bash - $ make help - ``` +```bash +$ make help +``` -4. Agent +#### Agent - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/agent - $ make - ``` +```bash +$ cd $GOPATH/src/github.com/clearcontainers/agent +$ make +``` - The agent is installed inside the root filesystem image - used by the hypervisor, hence to test a new agent version it is - necessary to create a custom rootfs image. The example below - demonstrates how to do this using the +The agent is installed inside the root filesystem image +used by the hypervisor, hence to test a new agent version it is +necessary to create a custom rootfs image. The example below +demonstrates how to do this using the [osbuilder](https://github.com/clearcontainers/osbuilder) tooling. - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/osbuilder +```bash +$ cd $GOPATH/src/github.com/clearcontainers/osbuilder - $ # Create a rootfs image - $ sudo -E make rootfs USE_DOCKER=true +$ # Create a rootfs image +$ sudo -E make rootfs USE_DOCKER=true - $ # Overwrite the default cc-agent binary with a custom built version - $ sudo cp $GOPATH/src/github.com/clearcontainers/agent/cc-agent ./workdir/rootfs/usr/bin/cc-agent +$ # Overwrite the default cc-agent binary with a custom built version +$ sudo cp $GOPATH/src/github.com/clearcontainers/agent/cc-agent ./workdir/rootfs/usr/bin/cc-agent - $ # Generate a container.img file - $ sudo -E make image USE_DOCKER=true +$ # Generate a container.img file +$ sudo -E make image USE_DOCKER=true - $ # Install the custom image - $ sudo install --owner root --group root --mode 0755 workdir/container.img /usr/share/clear-containers/ +$ # Install the custom image +$ sudo install --owner root --group root --mode 0755 workdir/container.img /usr/share/clear-containers/ - $ # Update the runtime configuration - $ # (note that this is only an example using default paths). - $ sudo sed -i.bak -e 's!^\(image = ".*"\)!# \1 \ - image = "/usr/share/clear-containers/container.img"!g' \ - /usr/share/defaults/clear-containers/configuration.toml - ``` +$ # Update the runtime configuration +$ # (note that this is only an example using default paths). +$ sudo sed -i.bak -e 's!^\(image = ".*"\)!# \1 \ +image = "/usr/share/clear-containers/container.img"!g' \ +/usr/share/defaults/clear-containers/configuration.toml +``` -5. Kernel +#### Kernel - The latest kernel for Clear Linux can be found on - [the releases page](https://github.com/clearcontainers/linux/releases). - The Clear Linux kernel can be used to rebuild and modify a custom VM - container kernel as needed. The example below demonstrates how to do this - using the [osbuilder](https://github.com/clearcontainers/osbuilder) tooling. +The latest kernel for Clear Linux can be found on +[the releases page](https://github.com/clearcontainers/linux/releases). +The Clear Linux kernel can be used to rebuild and modify a custom VM +container kernel as needed. The example below demonstrates how to do this +using the [osbuilder](https://github.com/clearcontainers/osbuilder) tooling. - ```bash - $ cd $GOPATH/src/github.com/clearcontainers/osbuilder +```bash +$ cd $GOPATH/src/github.com/clearcontainers/osbuilder - $ # Fetch latest kernel sources from github.com/clearcontainers/linux - $ make kernel-src +$ # Fetch latest kernel sources from github.com/clearcontainers/linux +$ make kernel-src - $ # Optionally modify kernel sources or config at $PWD/workdir/linux +$ # Optionally modify kernel sources or config at $PWD/workdir/linux - $ # build kernel - $ make kernel +$ # build kernel +$ make kernel - $ # Install the custom image - $ sudo install --owner root --group root --mode 0755 workdir/vmlinuz.container /usr/share/clear-containers/custom-vmlinuz - $ sudo install --owner root --group root --mode 0755 workdir/vmlinux.container /usr/share/clear-containers/custom-vmlinux +$ # Install the custom image +$ sudo install --owner root --group root --mode 0755 workdir/vmlinuz.container /usr/share/clear-containers/custom-vmlinuz +$ sudo install --owner root --group root --mode 0755 workdir/vmlinux.container /usr/share/clear-containers/custom-vmlinux - $ # Update the runtime configuration - $ # (note that this is only an example using default paths). - $ # Note: vmlinuz is used for pc platform type. - $ # vmlinux is used for pc-lite and q35-lite platform type. - $ sudo sed -i.bak -e 's!^\(kernel = ".*"\)!# \1\nkernel = "/usr/share/clear-containers/custom-vmlinuz"!g' \ - /usr/share/defaults/clear-containers/configuration.toml - ``` +$ # Update the runtime configuration +$ # (note that this is only an example using default paths). +$ # Note: vmlinuz is used for pc platform type. +$ # vmlinux is used for pc-lite and q35-lite platform type. +$ sudo sed -i.bak -e 's!^\(kernel = ".*"\)!# \1\nkernel = "/usr/share/clear-containers/custom-vmlinuz"!g' \ +/usr/share/defaults/clear-containers/configuration.toml +``` ## See Also From 7a6e9af121f2b94b71f757d187f9439bbcc944a0 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 13:54:21 +0000 Subject: [PATCH 10/11] docs: Removed blank line in dev guide Removed superfluous trailing blank line in dev guide. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index 7ba1e59a..c991c3ca 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -205,4 +205,3 @@ $ sudo sed -i.bak -e 's!^\(kernel = ".*"\)!# \1\nkernel = "/usr/share/clear-cont The repository used to create the packaged versions of Clear Containers components for various Linux distributions is: * https://github.com/clearcontainers/packaging - From dbd4f6abd93d95b027d0f7278f1997ca1537f910 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 4 Jan 2018 17:59:20 +0000 Subject: [PATCH 11/11] docs: Improving wording in dev guide Apply some non-PR-related review feedback. Signed-off-by: James O. D. Hunt --- docs/developers-clear-containers-install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developers-clear-containers-install.md b/docs/developers-clear-containers-install.md index c991c3ca..9557426f 100644 --- a/docs/developers-clear-containers-install.md +++ b/docs/developers-clear-containers-install.md @@ -139,7 +139,7 @@ $ make The agent is installed inside the root filesystem image used by the hypervisor, hence to test a new agent version it is -necessary to create a custom rootfs image. The example below +necessary to create a custom rootfs image. The following example demonstrates how to do this using the [osbuilder](https://github.com/clearcontainers/osbuilder) tooling. @@ -170,7 +170,7 @@ image = "/usr/share/clear-containers/container.img"!g' \ The latest kernel for Clear Linux can be found on [the releases page](https://github.com/clearcontainers/linux/releases). The Clear Linux kernel can be used to rebuild and modify a custom VM -container kernel as needed. The example below demonstrates how to do this +container kernel as needed. The following example demonstrates how to do this using the [osbuilder](https://github.com/clearcontainers/osbuilder) tooling. ```bash