Architecture overview

- also some tweaks in README.

fix #1394

Signed-off-by: Justin Cormack <justin.cormack@docker.com>

README.md

@@ -15,17 +15,16 @@ Moby, a toolkit for building custom minimal, immutable Linux distributions.
 
 ## Getting Started
 
-### Build
+### Build the `moby` tool
 
 Simple build instructions: use `make` to build.
-This will build the Moby customisation tool and a Moby initrd image.
+This will build the Moby customisation tool and an example Moby initrd image from the `moby.yml` file.
 
 If you already have a Go build environment and installed the source in your `GOPATH`
 you can do `go install github.com/docker/moby/cmd/moby` to install the `moby` tool
 instead, and then use `moby build moby.yml` to build the example configuration.
 
-#### Build requirements
+Build requirements:
-
 - GNU `make`
 - GNU or BSD `tar` (not `busybox` `tar`)
 - Docker
@@ -41,15 +40,18 @@ The Makefile also specifies a number of targets:
 - There are also docs for booting on [Google Cloud](docs/gcp.md)
 - More detailed docs will be available shortly, for running single hosts and clusters.
 
-## Customise
+## Building your own customised image
 
-To customise, copy or modify the [`moby.yml`](moby.yml) to your own `file.yml` or use on of the [examples](examples/) and then run `./bin/moby build file.yml` to
+To customise, copy or modify the [`moby.yml`](moby.yml) to your own `file.yml` or use one of the [examples](examples/) and then run `./bin/moby build file.yml` to
 generate its specified output. You can run the output with `./scripts/qemu.sh` or on OSX with `./bin/moby run file`. `moby run` targets will be available for other
-platforms shortly. 
+platforms shortly.
+
+The yaml file specifies a kernel and base init system, a set of containers that are built into the generated image and started at boot time. It also specifies what
+formats to output, such as bootable ISOs and images for various platforms.
 
 ### Yaml Specification
 
-The Yaml format is loosely based on Docker Compose:
+The yaml format is loosely based on Docker Compose:
 
 - `kernel` specifies a kernel Docker image, containing a kernel and a filesystem tarball, eg containing modules. `mobylinux/kernel` is built from `kernel/`
 - `init` is the base `init` process Docker image, which is unpacked as the base system, containing `init`, `containerd`, `runc` and a few tools. Built from `base/init/`
@@ -63,6 +65,11 @@ there are no volumes only `binds`.
 
 The config is liable to be changed, and there are missing features; full documentation will be available shortly.
 
+
+## Architecture
+
+There is an [overview of the architecture](architecture/) covering how the system works.
+
 ## Roadmap
 
 This project was extensively reworked from the code we are shipping in Docker Editions, and the result is not yet production quality. The plan is to return to production

docs/architecture.md

@@ -0,0 +1,66 @@
+# Architecture
+
+The `moby` tool converts the yaml specification into one or more bootable images.
+
+A kernel image is a Docker image with a `bzImage` file for the kernel to be executed,
+and a tarball `kernel.tar` containing any modules. This is somewhat inconsistent with
+the other images (see below) and may be changed. The kernel build is in the
+[`kernel/`](kernel/) directory.
+
+For all other images, ie `init` and the system containers and daemons, the filesystem
+of the container is extracted. The `init` and `kernel` filesystems are left unchanged,
+while the other containers are currently extracted under the `containers/` directory
+where the `init` script runs them. In future they may be extracted to the `containerd`
+image store instead. The builds and source for these containers can be found in the
+[`pkg/` directory)(pkg/).
+
+The `init` that is being used is being reworked, as an earlier incarnation was much
+less containerised and we ran a full Alpine Linux distribution here. It should end
+up as just `init`, a basic setup script, and `containerd`, with `mdev` and `getty`
+moved into containers.
+
+The system containers are fairly low level, and most users will probably want to
+start with something based on the examples. The aim is to provide a base set that
+covers general setup (such as `sysfs` to configure that, and a container to provide
+`dhcp` which many platforms use), and a set of platform specific ones, for example
+the `metadata-*` ones which will get userdata from cloud providers. There will be
+some `dev` containers to allow easy access to the system, for example with `ssh`.
+Then there will be some common applications.
+
+For each system or daemon container, an OCI `config.json` file is generated. This is
+currently done via a modified version of `riddler` running in a container but will
+soon be switched to run directly from the config. This is added to the built image
+so it can be called at runtime.
+
+Once all the container filesystems have been unpacked, they are joined into a Linux
+initramfs, which is a compressed `cpio` archive. This and the kernel can be booted
+directly on some platforms, such as qemu or hyperkit, but other platforms need these
+to have a bootloader added, so this is done by the output formats.
+
+The `kernel+initrd` target outputs the raw kernel and initramfs, as well as a file
+with the specified command line. It can be used to build other targets or used by
+scripts directly.
+
+The output formats are all, except the simple `kernel+initrd` target, generated via
+Docker containers, as there are not yet good libraries for outputting these formats
+in Go. Most of the current ones create an ISO or ext4 filesystem with `syslinux`
+as a boot loader, which directly boots the kernel and initramfs. This is not a requirement
+and other bootloaders can be used, and the filesystem could be unpacked onto the
+media if required too, or a more complex boot loader scheme used, such as the one
+ChromeOS has, with upgrade and fallback facilities.
+
+Because the image is run as an initramfs, and the system containers are
+baked in, upgrades are done by updating the system externally. This makes the whole
+system immutable, the [phoenix server](https://martinfowler.com/bliki/ImmutableServer.html)
+model.Persistent storage can be added using a volume (examples coming soon based on
+what the Docker Editions use). For running programs dynamically, a container
+orchestrator such as Docker or Kubernetes can be used; simpler distributed applications
+can be hard coded into the initramfs if they are suited to being run directly on
+immutable infrastructure.
+
+In production we expect most users will use a cluster of instances, usually running
+distributed applications, such as `etcd`, `Docker`, `Kubernetes` or distributed
+databases. We will provide examples of how to run these effectively, largely using
+`infrakit`, although other machine orchestration systems can equally well be used,
+for example Terraform or VMWare, and we welcome examples and documentation for those
+too.