Add apt-based instructions.

9 files changed, 220 insertions, 61 deletions

diff --git a/content/docs/includes/index.md b/content/docs/includes/index.md
deleted file mode 100644
index cbb7365a6..000000000
--- a/content/docs/includes/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-+++
-headless = true
-+++
diff --git a/content/docs/includes/install_gvisor.md b/content/docs/includes/install_gvisor.md
deleted file mode 100644
index 5a10d4054..000000000
--- a/content/docs/includes/install_gvisor.md
+++ /dev/null
@@ -1,37 +0,0 @@
-The easiest way to get `runsc` is from the [latest nightly
-build][latest-nightly]. After you download the binary, check it against the
-SHA512 [checksum file][latest-hash].
-
-Older builds can also be found here (note that some days may not have releases
-due to failing builds):
-
-   `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc`
-
-With corresponding SHA512 checksums here:
-
-   `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc.sha512`
-
-**It is important to copy this binary to a location that is accessible to all
-users, and ensure it is executable by 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.
-
-```bash
-(
-  set -e 
-  if [ -e runsc ]; then rm runsc; fi
-  wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
-  if [ -e runsc.sha512 ]; then rm runsc.sha512; fi
-  wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
-  sha512sum -c runsc.sha512
-  sudo mv runsc /usr/local/bin
-  sudo chown root:root /usr/local/bin/runsc
-  sudo chmod 0755 /usr/local/bin/runsc
-)
-```
-
-[latest-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
-
-[latest-hash]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
-
-[oci]: https://www.opencontainers.org
diff --git a/content/docs/user_guide/_index.md b/content/docs/user_guide/_index.md
index 803ad00f1..c01220314 100644
--- a/content/docs/user_guide/_index.md
+++ b/content/docs/user_guide/_index.md
@@ -3,10 +3,5 @@ title = "User Guide"
 weight = 10
 +++
 
-gVisor can be used with Docker, Kubernetes, or directly using `runsc` with crafted OCI 
-spec for your container. Use the links below to see detailed instructions for each
-of them:
-
- * [Docker](./docker/): The quickest and easiest way to get started.
- * [Kubernetes](./kubernetes/): Isolate Pods in your K8s cluster with gVisor.
- * [OCI Quick Start](./oci/): Expert mode. Customize gVisor for your environment.
+Get started with either [installation instructions](./install/) or
+[quick start guides](./quick_start).
diff --git a/content/docs/user_guide/install.md b/content/docs/user_guide/install.md
new file mode 100644
index 000000000..cdfb0ff96
--- /dev/null
+++ b/content/docs/user_guide/install.md
@@ -0,0 +1,162 @@
++++
+title = "Installation"
+weight = 20
++++
+
+> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}}
+> ([older Linux][old-linux]).
+
+## Versions
+
+The `runsc` binaries and repositories are available in multiple versions and
+release channels. First, you should pick the version you'd like to install. For
+experimentation, the nightly release is recommended. For production use, the
+latest release is recommended.
+
+After selecting an appropriate release channel from the options below, proceed
+to the preferred installation mechanism: manual or from an `apt` repository.
+
+### Nightly
+
+Nightly releases are built most nights from the master branch, and are available
+at the following URL:
+
+   `https://storage.googleapis.com/gvisor/releases/nightly/latest`
+
+Specific nightly releases can be found at:
+
+   `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}`
+
+Note that a release may not be available for every day.
+
+To use a nightly release, use one of the above URLs for `URL` in the manual
+instructions below. For `apt`, use `nightly` for `DIST` below.
+
+### Latest release
+
+The latest official release is available at the following URL:
+
+   `https://storage.googleapis.com/gvisor/releases/release/latest`
+
+To use the latest release, use the above URL for `URL` in the manual
+instructions below. For `apt`, use `latest` for `DIST` below.
+
+### Specific release
+
+A given release release is available at the following URL:
+
+  `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}`
+
+See the [releases][releases] page for information about specific releases.
+
+This will include point updates for the release, if required. To use a specific
+release, use the above URL for `URL` in the manual instructions below. For
+`apt`, use `${yyyymmdd}` for `DIST` below.
+
+### Point release
+
+A given point release is available at the following URL:
+
+  `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}`
+
+Unlike the specific release above, which may include updates, this release will
+not change. To use a specific point release, use the above URL for `URL` in the
+manual instructions below. For apt, use `${yyyymmdd}.${rc}` for `DIST` below.
+
+## From an `apt` repository
+
+First, appropriate dependencies must be installed to allow `apt` to install
+packages via https:
+
+```bash
+sudo apt-get update && \
+sudo apt-get install -y \
+    apt-transport-https \
+    ca-certificates \
+    curl \
+    gnupg-agent \
+    software-properties-common
+```
+
+Next, the key used to sign archives should be added to your `apt` keychain:
+
+```bash
+curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add -
+```
+
+Based on the release type, you will need to substitute `${DIST}` below, using
+one of:
+
+ * `nightly`: For all nightly releases.
+ * `latest`: For the latest release.
+ * `${yyyymmdd}`: For specific releases.
+ * `${yyyymmdd}.${rc}`: For a specific point release.
+
+The repository for the release you wish to install should be added:
+
+```bash
+sudo add-apt-repository \
+   "deb https://storage.googleapis.com/gvisor/releases" \
+   "${DIST}" \
+   main
+```
+
+For example, to install the latest official release, you can use:
+
+```bash
+sudo add-apt-repository \
+   "deb https://storage.googleapis.com/gvisor/releases" \
+   latest \
+   main
+```
+
+Now the runsc package can be installed:
+
+```bash
+sudo apt-get update && sudo apt-get install -y runsc
+```
+
+If you have Docker installed, it will be automatically configured.
+
+## Manually
+
+After selecting an appropriate `URL` above, you can download `runsc` directly
+from `${URL}/runsc` ([latest][latest-nightly]) and a checksum hash from
+`${URL}/runsc.sha512` ([latest][latest-hash]).
+
+For example, this binary can be downloaded, validated, and placed in an
+appropriate location by running:
+
+```bash
+(
+  set -e
+  wget ${URL}/runsc
+  wget ${URL/runsc.sha512
+  sha512sum -c runsc.sha512
+  sudo mv runsc /usr/local/bin
+  sudo chown root:root /usr/local/bin/runsc
+  sudo chmod 0755 /usr/local/bin/runsc
+)
+```
+
+**It is important to copy this binary to a location that is accessible to all
+users, and ensure it is executable by 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.
+
+After installation, the`runsc` binary comes with an `install` command that can
+optionally automatically configure Docker:
+
+```bash
+runsc install
+```
+
+[latest-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
+
+[latest-hash]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
+
+[oci]: https://www.opencontainers.org
+
+[old-linux]: /docs/user_guide/networking/#gso
+
+[releases]: https://github.com/google/gvisor/releases
diff --git a/content/docs/user_guide/quick_start/_index.md b/content/docs/user_guide/quick_start/_index.md
new file mode 100644
index 000000000..770fd8893
--- /dev/null
+++ b/content/docs/user_guide/quick_start/_index.md
@@ -0,0 +1,12 @@
++++
+title = "Quick Start"
+weight = 10
++++
+
+gVisor can be used with Docker, Kubernetes, or directly using `runsc` with
+crafted OCI spec for your container. Use the links below to see detailed
+instructions for each of them:
+
+ * [Docker](./docker/): The quickest and easiest way to get started.
+ * [Kubernetes](./kubernetes/): Isolate Pods in your K8s cluster with gVisor.
+ * [OCI](./oci/): Expert mode. Customize gVisor for your environment.
diff --git a/content/docs/user_guide/docker.md b/content/docs/user_guide/quick_start/docker.md
index 99cb766ff..523831c1b 100644
--- a/content/docs/user_guide/docker.md
+++ b/content/docs/user_guide/quick_start/docker.md
@@ -1,22 +1,23 @@
 +++
-title = "Docker Quick Start"
+title = "Docker"
 weight = 10
 +++
+
+> Note: This guide requires Docker version 17.09.0 or greater. Refer to the
+> [Docker documentation][docker] for how to install it.
+
 This guide will help you quickly get started running Docker containers using
 gVisor.
 
 ## Install gVisor
 
-> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}}
-> ([older Linux][old-linux]).
+First, install gVisor using the [install instructions][install].
 
-{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}}
+If you use the `apt` repository or the `automated` install, then you can skip
+the next section and proceed straight to running a container.
 
 ## Configuring Docker
 
-> Note: This guide requires Docker version 17.09.0 or greater. Refer to the
-> [Docker documentation][docker] for how to install it.
-
 First you will need to 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
@@ -88,5 +89,5 @@ Next, look at the different options available for gVisor: [platform](../platform
 [network](../networking/), [filesystem](../filesystem/).
 
 [docker]: https://docs.docker.com/install/
-[old-linux]: /docs/user_guide/networking/#gso
+
 [storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver
diff --git a/content/docs/user_guide/kubernetes.md b/content/docs/user_guide/quick_start/kubernetes.md
index 3aa5c719b..b3b5e0a55 100644
--- a/content/docs/user_guide/kubernetes.md
+++ b/content/docs/user_guide/quick_start/kubernetes.md
@@ -2,6 +2,7 @@
 title = "Kubernetes"
 weight = 20
 +++
+
 gVisor can be used to run Kubernetes pods and has several integration points
 with Kubernetes.
 
diff --git a/content/docs/user_guide/oci.md b/content/docs/user_guide/quick_start/oci.md
index 288575fc4..b39be069e 100644
--- a/content/docs/user_guide/oci.md
+++ b/content/docs/user_guide/quick_start/oci.md
@@ -1,16 +1,14 @@
 +++
-title = "OCI Quick Start"
+title = "OCI"
 weight = 30
 +++
+
 This guide will quickly get you started running your first gVisor sandbox
 container using the runtime directly with the default platform.
 
 ## Install gVisor
 
-> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}}
-> ([older Linux][old-linux]).
-
-{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}}
+First, install gVisor using the [install instructions][install].
 
 ## Run an OCI compatible container
 
@@ -48,4 +46,5 @@ sudo runsc run hello
 Next try [running gVisor using Docker](../docker/).
 
 [oci]: https://opencontainers.org/
-[old-linux]: /docs/user_guide/networking/#gso
+
+[install]: /docs/user_guide/install
diff --git a/static/archive.key b/static/archive.key
new file mode 100644
index 000000000..1a91698bf
--- /dev/null
+++ b/static/archive.key
@@ -0,0 +1,29 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQINBF0meAYBEACcBYPOSBiKtid+qTQlbgKGPxUYt0cNZiQqWXylhYUT4PuNlNx5
+s+sBLFvNTpdTrXMmZ8NkekyjD1HardWvebvJT4u+Ho/9jUr4rP71cNwNtocz/w8G
+DsUXSLgH8SDkq6xw0L+5eGc78BBg9cOeBeFBm3UPgxTBXS9Zevoi2w1lzSxkXvjx
+cGzltzMZfPXERljgLzp9AAfhg/2ouqVQm37fY+P/NDzFMJ1XHPIIp9KJl/prBVud
+jJJteFZ5sgL6MwjBQq2kw+q2Jb8Zfjl0BeXDgGMN5M5lGhX2wTfiMbfo7KWyzRnB
+RpSP3BxlLqYeQUuLG5Yx8z3oA3uBkuKaFOKvXtiScxmGM/+Ri2YM3m66imwDhtmP
+AKwTPI3Re4gWWOffglMVSv2sUAY32XZ74yXjY1VhK3bN3WFUPGrgQx4X7GP0A1Te
+lzqkT3VSMXieImTASosK5L5Q8rryvgCeI9tQLn9EpYFCtU3LXvVgTreGNEEjMOnL
+dR7yOU+Fs775stn6ucqmdYarx7CvKUrNAhgEeHMonLe1cjYScF7NfLO1GIrQKJR2
+DE0f+uJZ52inOkO8ufh3WVQJSYszuS3HCY7w5oj1aP38k/y9zZdZvVvwAWZaiqBQ
+iwjVs6Kub76VVZZhRDf4iYs8k1Zh64nXdfQt250d8U5yMPF3wIJ+c1yhxwARAQAB
+tCpUaGUgZ1Zpc29yIEF1dGhvcnMgPGd2aXNvci1ib3RAZ29vZ2xlLmNvbT6JAlQE
+EwEKAD4WIQRvHfheOnHCSRjnJ9VvxtVU4yvZQwUCXSZ4BgIbAwUJA8JnAAULCQgH
+AgYVCgkICwIEFgIDAQIeAQIXgAAKCRBvxtVU4yvZQ5WFD/9VZXMW5I2rKV+2gTHT
+CsW74kZVi1VFdAVYiUJZXw2jJNtcg3xdgBcscYPyecyka/6TS2q7q2fOGAzCZkcR
+e3lLzkGAngMlZ7PdHAE0PDMNFaeMZW0dxNH68vn7AiA1y2XwENnxVec7iXQH6aX5
+xUNg2OCiv5f6DJItHc/Q4SvFUi8QK7TT/GYE1RJXVJlLqfO6y4V8SeqfM+FHpHZM
+gzrwdTgsNiEm4lMjWcgb2Ib4i2JUVAjIRPfcpysiV5E7c3SPXyu4bOovKKlbhiJ1
+Q1M9M0zHik34Kjf4YNO1EW936j7Msd181CJt5Bl9XvlhPb8gey/ygpIvcicLx6M5
+lRJTy4z1TtkmtZ7E8EbJZWoPTaHlA6hoMtGeE35j3vMZN1qZYaYt26eFOxxhh7PA
+J0h1lS7T2O8u1c2JKhKvajtdmbqbJgI8FRhVsMoVBnqDK5aE9MOAso36OibfweEL
+8iV2z8JnBpWtbbUEaWro4knPtbLJbQFvXVietm3cFsbGg+DMIwI6x6HcU91IEFYI
+Sv4orK7xgLuM+f6dxo/Wel3ht18dg3x3krBLALTYBidRfnQYYR3sTfLquB8b5WaY
+o829L2Bop9GBygdLevkHHN5It6q8CVpn0H5HEJMNaDOX1LcPbf0CKwkkAVCBd9YZ
+eAX38ds9LliK7XPXdC4c+zEkGA==
+=x8TG
+-----END PGP PUBLIC KEY BLOCK-----