[lxc-devel] [distrobuilder/master] doc: Added usage instructions in Readme.md
simos on Github
lxc-bot at linuxcontainers.org
Wed Oct 3 12:36:55 UTC 2018
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 548 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20181003/cd3773f8/attachment.bin>
-------------- next part --------------
From 1de48a34eae02c2907dca31c2a9c94161ce215b8 Mon Sep 17 00:00:00 2001
From: Simos Xenitellis <simos.lists at googlemail.com>
Date: Wed, 3 Oct 2018 15:32:40 +0300
Subject: [PATCH] doc: Added usage instructions in Readme.md
Signed-off-by: Simos Xenitellis <simos.lists at googlemail.com>
---
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 at 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 at 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 at 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
+```
More information about the lxc-devel
mailing list