The following pull request was submitted through Github. It can be accessed and reviewed at: https://github.com/lxc/distrobuilder/pull/111
This e-mail was sent by the LXC bot, direct replies will not reach the author unless they happen to be subscribed to this list. === Description (from pull-request) === The instructions show how to use `distrobuilder` to create a container image for Ubuntu, then use it to launch a container. The instructions emphasize the terminology `container image`, which I believe is a suitable for these images.
From 1de48a34eae02c2907dca31c2a9c94161ce215b8 Mon Sep 17 00:00:00 2001 From: Simos Xenitellis <[email protected]> Date: Wed, 3 Oct 2018 15:32:40 +0300 Subject: [PATCH] doc: Added usage instructions in Readme.md Signed-off-by: Simos Xenitellis <[email protected]> --- README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 118 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cbf1fd2..e8fecb1 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,122 @@ Type | Service | Status CI | Jenkins | [](https://travis-ci.org/lxc/distrobuilder) Project status | CII Best Practices | [](https://bestpractices.coreinfrastructure.org/projects/1728) -## Example usage -Save one of the [Ubuntu yaml snippets](./doc/examples/ubuntu) as -`ubuntu.yaml`. To create a simple `Ubuntu` rootfs in a folder called -`ubuntu-rootfs` call `distrobuilder` as `distrobuilder build-dir ubuntu.yaml -ubuntu-rootfs`. +## Command line options + +The following are the command line options of `distrobuilder`. You can use `distrobuilder` to create container images for both LXC and LXD. + +```bash +$ distrobuilder +System container image builder for LXC and LXD + +Usage: + distrobuilder [command] + +Available Commands: + build-dir Build plain rootfs + build-lxc Build LXC image from scratch + build-lxd Build LXD image from scratch + help Help about any command + pack-lxc Create LXC image from existing rootfs + pack-lxd Create LXD image from existing rootfs + +Flags: + --cache-dir Cache directory + --cleanup Clean up cache directory (default true) + -h, --help help for distrobuilder + -o, --options Override options (list of key=value) + +Use "distrobuilder [command] --help" for more information about a command. +``` + +## How to use + +In the following, we see how to create a container image for LXD. + +### Installation + +Currently, there are no binary packages of `distrobuilder`. Therefore, you will need to compile it from source. +To do so, first install the Go programming language and the `debootstrap` package. + +``` +sudo apt update +sudo apt install -y golang-go +sudo apt install -y debootstrap +``` + +Second, download the source code of the `distrowatch` repository (this repository). The source will be placed in `$HOME/go/src/github.com/lxc/distrobuilder/` + +``` +go get -d -v github.com/lxc/distrobuilder +``` + +Third, enter the directory with the source code of `distrobuilder` and run `make` to compile the source code. This will generate the executable program `distrobuilder`, and it will be located at `$HOME/go/bin/distrobuilder`. + +``` +cd $HOME/go/src/github.com/lxc/distrobuilder +make +cd +``` + +### Creating a container image + +To create a container image, first create a directory where you will be placing the container images, and enter that directory. + +``` +mkdir -p $HOME/ContainerImages/ubuntu/ +cd $HOME/ContainerImages/ubuntu/ +``` + +Then, copy one of the example yaml configuration files for container images into this directory. In this example, we are creating an Ubuntu container image. + +``` +cp $HOME/go/src/github.com/lxc/distrobuilder/doc/examples/ubuntu ubuntu.yaml +``` + +Finally, run `distrobuilder` to create the container image. We are using the `build-lxd` option to create a container image for LXD. + +``` +sudo $HOME/go/bin/distrobuilder build-lxd ubuntu.yaml +``` + +If the command is successful, you will get an output similar to the following. The `lxd.tar.xz` file is the description of the container image. The `rootfs.squasfs` file is the root filesystem (rootfs) of the container image. The set of these two files is the _container image_. + +```bash +multipass@dazzling-termite:~/ContainerImages/ubuntu$ ls -l +total 121032 +-rw-r--r-- 1 root root 560 Oct 3 13:28 lxd.tar.xz +-rw-r--r-- 1 root root 123928576 Oct 3 13:28 rootfs.squashfs +-rw-rw-r-- 1 multipass multipass 3317 Oct 3 13:19 ubuntu.yaml +multipass@dazzling-termite:~/ContainerImages/ubuntu$ +``` + +### Adding the container image to LXD + +To add the container image to a LXD installation, use the `lxc image import` command as follows. + +```bash +multipass@dazzling-termite:~/ContainerImages/ubuntu$ lxc image import lxd.tar.xz rootfs.squashfs --alias mycontainerimage +Image imported with fingerprint: ae81c04327b5b115383a4f90b969c97f5ef417e02d4210d40cbb17a038729a27 +``` + +Let's see the container image in LXD. The `ubuntu.yaml` had a setting to create an Ubuntu 17.10 (`artful`) image. The size is 118MB. + +```bash +$ lxc image list mycontainerimage ++------------------+--------------+--------+---------------+--------+----------+------------------------------+ +| ALIAS | FINGERPRINT | PUBLIC | DESCRIPTION | ARCH | SIZE | UPLOAD DATE | ++------------------+--------------+--------+---------------+--------+----------+------------------------------+ +| mycontainerimage | ae81c04327b5 | no | Ubuntu artful | x86_64 | 118.19MB | Oct 3, 2018 at 12:09pm (UTC) | ++------------------+--------------+--------+---------------+--------+----------+------------------------------+ +``` + +### Launching a container from the container image + +To launch a container from the freshly created container image, use `lxc launch` as follows. Note that you do not specify a repository of container images (like `ubuntu:` or `images:`) because the image is located locally. + +``` +$ lxc launch mycontainerimage c1 +Creating c1 +Starting c1 +```
_______________________________________________ lxc-devel mailing list [email protected] http://lists.linuxcontainers.org/listinfo/lxc-devel
