From db0473b1bec1481e5a7807752b5eaa72c816c562 Mon Sep 17 00:00:00 2001
From: Ian Lewis <ianlewis@google.com>
Date: Thu, 29 Nov 2018 04:48:15 -0800
Subject: Add a new docs directory. refs #109

Add a new 'docs' directory for that can be built on in the future. Docs are
divided into a 'user guide', 'contributor guide', and 'architecture guide'.
This is currently a work in progress.

PiperOrigin-RevId: 223326836
Change-Id: I78d08d6a89d686e92d3415d4269463e8e74bddee
---
 docs/user_guide/README.md      |  1 +
 docs/user_guide/docker.md      | 41 ++++++++++++++++++++++++
 docs/user_guide/quick_start.md | 71 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 113 insertions(+)
 create mode 100644 docs/user_guide/README.md
 create mode 100644 docs/user_guide/docker.md
 create mode 100644 docs/user_guide/quick_start.md

(limited to 'docs/user_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
-- 
cgit v1.2.3