From 3e0e112e2bcf43ab3c92e351b90bd5e6f1a0c8ec Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Fri, 20 Apr 2018 14:42:51 +0100 Subject: [PATCH 1/2] docs: Move TOC to top Move the table of contents to the top of the page. Signed-off-by: James O. D. Hunt --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fcf815af64..158a41a594 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,11 @@ -# osbuilder [![Build Status](https://travis-ci.org/kata-containers/osbuilder.svg?branch=master)](https://travis-ci.org/kata-containers/osbuilder) +[![Build Status](https://travis-ci.org/kata-containers/osbuilder.svg?branch=master)](https://travis-ci.org/kata-containers/osbuilder) + +# osbuilder + +* [Introduction](#introduction) +* [Terms](#terms) + +## Introduction The Kata Containers runtime creates a virtual machine (VM) to isolate a set of container workloads. The VM requires a guest kernel and a guest operating system @@ -7,9 +14,6 @@ environment. This repository contains tools to create a guest OS disk image. -## Table of Contents -* [Terms](#terms) - ## Terms This section describes the terms used for all documentation in this repository. From 3c19ea413e488b2758a6017393d5c485f4a932ba Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Fri, 20 Apr 2018 15:02:15 +0100 Subject: [PATCH 2/2] docs: Add a Usage section Add a new Usage section with basic examples of how to run the builders from the `Makefile`. Fixes #84. Signed-off-by: James O. D. Hunt --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 158a41a594..fb17e8496a 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,14 @@ * [Introduction](#introduction) * [Terms](#terms) +* [Usage](#usage) + * [Rootfs creation](#rootfs-creation) + * [Rootfs with systemd as init](#rootfs-with-systemd-as-init) + * [Rootfs with the agent as init](#rootfs-with-the-agent-as-init) + * [Image creation](#image-creation) + * [Image with systemd as init](#image-with-systemd-as-init) + * [Image with the agent as init](#image-with-the-agent-as-init) + * [Initrd creation](#initrd-creation) ## Introduction @@ -20,10 +28,9 @@ This section describes the terms used for all documentation in this repository. - rootfs - The root filesystem or "rootfs" is the set of files contained in the - guest root directory that builds into a filesystem. + The root filesystem or "rootfs" is a slight misnomer as it is not a true filesystem. It is a tree of files contained in a particular directory, which represents the root disk layout. A rootfs can be turned into either an image or an initrd. - See [the rootfs builder documentation](rootfs-builder/README.md). + See the [rootfs creation](#rootfs-creation) section. - "Guest OS" (or "Guest Image") @@ -32,16 +39,71 @@ This section describes the terms used for all documentation in this repository. create an environment to host the container. Neither the guest OS nor the guest kernel need to be the same as the host operating system. - See [the image builder documentation](image-builder/README.md). + See the [image creation](#image-creation) section. - initrd (or "initramfs") - A compressed cpio archive loaded into memory and used as part of the Linux - startup process. During startup, the kernel unpacks it into a special - instance of a tmpfs that becomes the initial root file system. + A compressed `cpio(1)` archive, created from a rootfs which is loaded into memory and used as part of the Linux startup process. During startup, the kernel unpacks it into a special instance of a `tmpfs` that becomes the initial root filesystem. - See [the initrd builder documentation](initrd-builder/README.md). + See the [initrd creation](#initrd-creation) section. - "Base OS" - A particular version of a Linux distribution used to create a Guest OS from. + A particular version of a Linux distribution used to create a rootfs from. + +## Usage + +The top-level `Makefile` contains an example of how to use the available components. + +By default, components will run on the host system. However, some components +offer the ability to run from within Docker (for ease of setup) by setting the +`USE_DOCKER=true` variable. + +For more detailed information, consult the documentation for a particular component. + +### Rootfs creation + +This section shows how to build a basic rootfs using the default distribution. +For further details, see +[the rootfs builder documentation](rootfs-builder/README.md). + +#### Rootfs with systemd as init + +``` +$ sudo -E PATH=$PATH make USE_DOCKER=true rootfs +``` + +#### Rootfs with the agent as init + +``` +$ sudo -E PATH=$PATH make USE_DOCKER=true AGENT_INIT=yes rootfs +``` + +### Image creation + +This section shows how to create an image from the already-created rootfs. For +further details, see +[the image builder documentation](image-builder/README.md). + +#### Image with systemd as init + +``` +$ sudo -E PATH=$PATH make USE_DOCKER=true image-only +``` + +#### Image with the agent as init + +``` +$ sudo -E PATH=$PATH make USE_DOCKER=true AGENT_INIT=yes image-only +``` + +### Initrd creation + +To create an initrd from the already-created rootfs with the agent acting as the init daemon: + +``` +$ sudo -E PATH=$PATH make AGENT_INIT=yes initrd-only +``` + +For further details, +see[the initrd builder documentation](initrd-builder/README.md).