From b2c26cb63cc5a785fb96930e7f179db2f6c08aa7 Mon Sep 17 00:00:00 2001
From: "James O. D. Hunt" <james.o.hunt@intel.com>
Date: Thu, 25 Jan 2018 18:01:44 +0000
Subject: [PATCH] docs: Add README

Add a `README.md` that explains the purpose of this repository along
with pointers to the other repositories.

Fixes #1.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
---
 README.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 000000000..49adc96e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,125 @@
+<img src="https://www.openstack.org/assets/kata/kata-vertical-on-white.png" width="150">
+
+# Kata Containers
+
+* [Raising issues](#raising-issues)
+* [Kata Containers repositories](#kata-containers-repositories)
+* [Community](#community)
+* [Code Repositories](#code-repositories)
+    * [Kata Containers-developed components](#kata-containers-developed-components)
+        * [Agent](#agent)
+        * [KSM throttler](#ksm-throttler)
+        * [Proxy](#proxy)
+        * [Runtime](#runtime)
+        * [Shim](#shim)
+    * [Additional](#additional)
+        * [Hypervisor](#hypervisor)
+        * [Kernel](#kernel)
+* [Utilities](#utilities)
+    * [O/S builder](#o/s-builder)
+* [Test code](#test-code)
+* [Documentation](#documentation)
+* [Web content](#web-content)
+
+---
+
+Welcome to Kata Containers!
+
+The purpose of this repository is to act as a "top level" site for the project. Specifically it is used:
+
+- To provide a list of the various *other* [Kata Containers repositories](#kata-containers-repositories),
+  along with a brief explanation of their purpose.
+
+- To provide a general area for [Raising Issues](#raising-issues).
+
+## Raising issues
+
+This repository is used for [raising
+issues](https://github.com/kata-containers/kata-containers/issues/new):
+
+- That might affect multiple code repositories.
+
+- Where the raiser is unsure which repositories are affected.
+
+> **Note:**
+> 
+> - If an issue affects only a single component, it should be raised in that
+>   components repository.
+
+## Kata Containers repositories
+
+### Community
+
+The [Community](https://github.com/kata-containers/community) repository is
+the first place to go if you want to use or contribute to the project.
+
+### Code Repositories
+
+#### Kata Containers-developed components
+
+##### Agent
+
+The [`kata-agent`](https://github.com/kata-containers/agent) runs inside the
+virtual machine and sets up the container environment.
+
+##### KSM throttler
+
+The [`kata-ksm-throttler`](https://github.com/kata-containers/ksm-throttler)
+is an optional utility that monitors containers and deduplicates memory to
+maximize container density on a host.
+
+##### Proxy
+
+The [`kata-proxy`](https://github.com/kata-containers/proxy) is a process that
+runs on the host and co-ordinates access to the agent running inside the
+virtual machine.
+
+##### Runtime
+
+The [`kata-runtime`](https://github.com/kata-containers/runtime) is usually
+invoked by a container manager and provides high-level verbs to manage
+containers.
+
+##### Shim
+
+The [`kata-shim`](https://github.com/kata-containers/shim) is a process that
+runs on the host. It acts as though it is the workload (which actually runs
+inside the virtual machine). This shim is required to be compliant with the
+expectations of the [OCI runtime
+specification](https://github.com/opencontainers/runtime-spec).
+
+#### Additional
+
+##### Hypervisor
+
+The [`qemu`](https://github.com/kata-containers/qemu) hypervisor is used to
+create virtual machines for hosting the containers.
+
+##### Kernel
+
+The [`linux`](https://github.com/kata-containers/linux) kernel is used by the hypervisor to boot the guest image.
+
+### Documentation
+
+The [`documentation`](https://github.com/kata-containers/documentation)
+repository hosts documentation common to all code components.
+
+### Test code
+
+The [Tests](https://github.com/kata-containers/tests) repository hosts all
+test code except the unit testing code (which is kept in the same repository
+as the component it tests).
+
+### Utilities
+
+#### O/S builder
+
+The [osbuilder](https://github.com/kata-containers/osbuilder) tool can create
+a rootfs and a "mini O/S" image. This image is used by the hypervisor to setup
+the environment before switching to the workload.
+
+### Web content
+
+The
+[www.katacontainers.io](https://github.com/kata-containers/www.katacontainers.io)
+repository contains all sources for the https://www.katacontainers.io site.