From aa44e41587058154a437f09a3d05d7066318c779 Mon Sep 17 00:00:00 2001 From: Rolf Neugebauer Date: Thu, 3 Aug 2017 15:05:22 +0100 Subject: [PATCH] docs: Update docs, add document about packages Signed-off-by: Rolf Neugebauer --- README.md | 7 +++- docs/packages.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 docs/packages.md diff --git a/README.md b/README.md index 5005514fd..4bd8a0ba6 100644 --- a/README.md +++ b/README.md @@ -70,8 +70,9 @@ Currently supported platforms are: #### Running the Tests -The test suite uses [`rtf`](https://github.com/linuxkit/rtf) -To install this you should use `make bin/rtf && make install`. +The test suite uses [`rtf`](https://github.com/linuxkit/rtf) To +install this you should use `make bin/rtf && make install`. You will +also need to install `expect` on your system as some tests use it. To run the test suite: @@ -103,6 +104,8 @@ generate its specified output. You can run the output with `linuxkit run file`. 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. You can specify the type of artifact to build with the `moby` tool eg `moby build -output vhd linuxkit.yml`. +If you want to build your own packages, see this [document](docs/packages.md). + ### Yaml Specification The yaml format specifies the image to be built: diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 000000000..56ba1f308 --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,101 @@ +# LinuxKit packages + +LinuxKit packages a container images which are pull using the `moby` +tool and assembled into bootable Linux images. LinuxKit comes with a +number of [packages](../pkg) which are core part of LinuxKit, but +users can add their own packages to the YAML files. + +All LinuxKit packages are: +- Signed with Docker Content Trust. +- Multi-arch manifests to work on multiple architectures. +- Derived from well-known (and signed) sources for repeatable builds. +- Build with multi-stage builds to minimise their size. + + +## Building packages + +### Prerequisites + +Before you can build packages you need: +- Docker version 17.06 or newer. If you are on a Mac you also need + `docker-credential-osxkeychain.bin`, which comes with Docker for Mac. +- `make`, `notary`, `base64`, `jq`, and `expect` +- A custom copy of `manifest-tool` which you can build with `make + bin/manifest-tool`. `manifest-tool` must be in your path. + +Further, when building packages you need to be logged into hub with +`docker login` as some of the tooling extracts your hub credentials +during the build. + +### Build packages as a maintainer + +If you have write access to the `linuxkit` organisation on hub, you +should also be set up with signing keys for packages and your signing +key should have a passphrase, which we call `` throughout. + +All official LinuxKit packages are multi-arch manifests and most of +them are available for amd64 and aarm64. Official images *must* be +build on both architectures and they must be build *in sequence*, i.e., +they can't be build in parallel. + +To build a package on an architecture: + +``` +DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="" make +``` + +This will: +- Build a local images as `linuxkit/:-` +- Push it to hub +- Sign it with your key +- Create a manifest called `linuxkit/:` (note no `-`) +- Push the manifest to hub +- Sign the manifest + +If you repeat the same on another architecture, a new manifest will be +pushed and signed containing the previous and the new +architecture. The YAML files should consume the package as: +`linuxkit/:`. + + +Since it is not very good to have your passphrase in the clear (or +even stashed in your shell history), we recommend using a password +manager with a CLI interface, such as LastPass or `pass`. You can then +invoke `make` like this (for LastPass): + +``` +DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=$(lpass show --password) make +``` + +### Build packages as a developer + +If you want to develop packages or test them locally, it is best to +override the hub organisation used. You may also want to disable +signing while developing. A typical example would be: + +``` +make ORG=wombat NOTRUST=1 tag +``` + +This will create a local image: `wombat/:-` which +you can use in your local YAML files for testing. If you need to test +on other systems you can push the image to your hub account and pull +from a different system by issuing: + +``` +make ORG=wombat NOTRUST=1 push +``` + +This will push both `wombat/:-` and +`wombat/:` to hub. + +Finally, if you are tired of the long hashes you can override the hash +with: + +``` +make ORG=wombat NOTRUST=1 HASH=foo push +``` + +and this will create `wombat/:foo-` and +`wombat/:foo` for use in your YAML files. +