7 files changed, 161 insertions, 0 deletions

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..6f847fa4b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,37 @@
+# gVisor Documentation
+
+**This doc is a work in progress. For the definitive documentation please see
+the [README](../README.md)**
+
+gVisor is a user-space kernel, written in Go, that implements a substantial
+portion of the [Linux system call interface][linux-interface]. It provides an
+additional layer of isolation between running applications and the host
+operating system.
+
+gVisor includes an [Open Container Initiative (OCI)][oci] runtime called `runsc`
+that makes it easy to work with existing container tooling. The `runsc` runtime
+integrates with Docker and Kubernetes, making it simple to run sandboxed
+containers.
+
+Check out the [gVisor Quick Start](user_guide/quick_start.md) to get started
+using gVisor.
+
+gVisor takes a distinct approach to container sandboxing and makes a different
+set of technical trade-offs compared to existing sandbox technologies, thus
+providing new tools and ideas for the container security landscape.
+
+Check out [Why gVisor?](architecture_guide/why.md) for more on why we made
+gVisor.
+
+## How this documentation is organized
+
+-   The [Architecture Guide](architecture_guide/README.md) explains about
+    gVisor's architecture & design philosophy. Start here if you would like to
+    know more about how gVisor works and why it was created.
+-   The [User Guide](user_guide/README.md) contains info on how to use gVisor
+    and integrate it into your application or platform.
+-   The [Contributer Guide](contributer_guide/README.md) includes documentation
+    on how to build gVisor, run tests, and contribute to gVisor's development.
+
+[linux-interface]: https://en.wikipedia.org/wiki/Linux_kernel_interfaces
+[oci]: https://www.opencontainers.org
diff --git a/docs/architecture_guide/README.md b/docs/architecture_guide/README.md
new file mode 100644
index 000000000..fe0569721
--- /dev/null
+++ b/docs/architecture_guide/README.md
@@ -0,0 +1 @@
+# Architecture Guide
diff --git a/docs/architecture_guide/why.md b/docs/architecture_guide/why.md
new file mode 100644
index 000000000..2bf9c60fd
--- /dev/null
+++ b/docs/architecture_guide/why.md
@@ -0,0 +1,9 @@
+# Why gVisor?
+
+gVisor makes a different set of technical trade-offs compared to existing
+sandbox technologies, thus providing new tools and ideas for the container
+security landscape.
+
+As the developers of gVisor, we wanted an execution environment that was secure,
+simple, and lightweight and were able to make trade offs in other areas. We were
+not able to achieve that with existing solutions.
diff --git a/docs/contributor_guide/README.md b/docs/contributor_guide/README.md
new file mode 100644
index 000000000..83840bba3
--- /dev/null
+++ b/docs/contributor_guide/README.md
@@ -0,0 +1 @@
+# Contributor Guide
diff --git a/docs/user_guide/README.md b/docs/user_guide/README.md
new file mode 100644
index 000000000..cd3d45227
--- /dev/null
+++ b/docs/user_guide/README.md
@@ -0,0 +1 @@
+# User Guide
diff --git a/docs/user_guide/docker.md b/docs/user_guide/docker.md
new file mode 100644
index 000000000..fefb5f993
--- /dev/null
+++ b/docs/user_guide/docker.md
@@ -0,0 +1,41 @@
+# Run gVisor with Docker
+
+## Configuring Docker
+
+Next, configure Docker to use `runsc` by adding a runtime entry to your Docker
+configuration (`/etc/docker/daemon.json`). You may have to create this file if
+it does not exist. Also, some Docker versions also require you to [specify the
+`storage-driver` field][docker-storage-driver].
+
+In the end, the file should look something like:
+
+```
+{
+    "runtimes": {
+        "runsc": {
+            "path": "/usr/local/bin/runsc"
+        }
+    }
+}
+```
+
+You must restart the Docker daemon after making changes to this file, typically
+this is done via:
+
+```
+sudo systemctl restart docker
+```
+
+## Running a container
+
+Now run your container in `runsc`:
+
+```
+docker run --runtime=runsc hello-world
+```
+
+You can also run a terminal to explore the container.
+
+```
+docker run --runtime=runsc -it ubuntu /bin/bash
+```
diff --git a/docs/user_guide/quick_start.md b/docs/user_guide/quick_start.md
new file mode 100644
index 000000000..219c1ed63
--- /dev/null
+++ b/docs/user_guide/quick_start.md
@@ -0,0 +1,71 @@
+# Quick Start
+
+This guide will quickly get you started running your first gVisor sandbox
+container.
+
+Some requirements:
+
+-   gVisor requires Linux x86\_64 Linux 3.17+
+-   This guide requires Docker. Read the Docker documentation for how to install
+    it on how to [install Docker](https://docs.docker.com/install/)
+
+## Install gVisor
+
+The easiest way to get `runsc` is from the
+[latest nightly build][runsc-nightly]. After you download the binary, check it
+against the SHA512 [checksum file][runsc-nightly-sha]. Older builds can be found
+here:
+`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc` and
+`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc.sha512`
+
+**It is important to copy this binary to some place that is accessible to all
+users, and make is executable to all users**, since `runsc` executes itself as
+user `nobody` to avoid unnecessary privileges. The `/usr/local/bin` directory is
+a good place to put the `runsc` binary.
+
+```
+wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
+wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
+sha512sum -c runsc.sha512
+chmod a+x runsc
+sudo mv runsc /usr/local/bin
+```
+
+## Run an OCI compatible container
+
+Now we will create an [OCI][oci] container bundle to run our container. First we
+will create a root directory for our bundle.
+
+```
+$ mkdir bundle
+$ cd bundle
+```
+
+Create a root file system for the container. We will use the Docker hello-world
+image as the basis for our container.
+
+```
+$ mkdir rootfs
+$ docker export $(docker create hello-world) | tar -xf - -C rootfs
+```
+
+Next, create an specification file called `config.json` that contains our
+container specification. We will update the default command it runs to `/hello`
+in the `hello-world` container.
+
+```
+$ runsc spec
+$ sed -i 's;"sh";"/hello";' config.json
+```
+
+Finally run the container.
+
+```
+$ sudo runsc run hello
+```
+
+\[TODO]:# Add some next steps
+
+[runsc-nightly-sha]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
+[runsc-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
+[oci]: https://www.opencontainers.org