From 5ea46b9644914890d382c4841ccf1231d8868c40 Mon Sep 17 00:00:00 2001 From: Justin Cormack Date: Sun, 19 Mar 2017 20:32:16 +0000 Subject: [PATCH] Improve README - better summary of aims of project for new visitors Signed-off-by: Justin Cormack --- README.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 69c8f6b4a..6d5e7822b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ # Moby -Moby, a toolkit for custom Linux distributions +Moby, a toolkit for building custom minimal, immutable Linux distributions. + +- Good, secure defaults included +- Everything is replaceable and customisable +- Immutable infrastructure applied to building Linux distributions +- Completely stateless, but persistent storage can be attached +- Easy tooling, with easy iteration +- Built with containers, for running containers +- Designed for building and running clustered applications, including but not limited to container orchestration such as Docker or Kubernetes +- Designed from the experience of building Docker Editions, but redesigned as a general purpose toolkit +- Designed to be managed by external tooling, such as [Infrakit](https://github.com/docker/infrakit) or similar tools +- Includes a set of longer term collaborative projects in various stages of development to innovate on kernel and userspace changes, particularly around security ## Getting Started @@ -9,22 +20,25 @@ Moby, a toolkit for custom Linux distributions Simple build instructions: use `make` to build. This will build the Moby customisation tool and a Moby initrd image. -#### Requirements: +#### Build requirements - GNU `make` -- GNU or BSD `tar` (not Busybox tar) +- GNU or BSD `tar` (not `busybox` `tar`) - Docker ### Booting and Testing - `make qemu` will boot up a sample Moby in qemu in a container -- on OSX: `make hyperkit` will boot up Moby in hyperkit, and also download hyperkit and vpnkit binaries for later use +- on OSX: `make hyperkit` will boot up Moby in hyperkit - `make test` or `make hyperkit-test` will run the test suite +- 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 -To customise, copy or modify the [`moby.yaml`](moby.yaml) to your own `file.yaml` and then run `./bin/moby file.yaml` to -generate its specified output. You can run the output with `./scripts/qemu.sh` or `./scripts/hyperkit.sh`. +To customise, copy or modify the [`moby.yaml`](moby.yaml) to your own `file.yaml` or use on of the [examples](examples/) and then run `./bin/moby file.yaml` to +generate its specified output. You can run the output with `./scripts/qemu.sh` or `./scripts/hyperkit.sh`, or on other +platforms. ### Yaml Specification @@ -40,4 +54,4 @@ The Yaml format is loosely based on Docker Compose: For the images, you can specify the configuration much like Compose, with some changes, eg `capabilities` must be specified in full, rather than `add` and `drop`, and there are no volumes only `binds`. -The config is liable to be changed, eg there are missing features (specification of kernel command line, more options etc). +The config is liable to be changed, and there are missing features; full documentation will be available shortly.