Updated installation instructions and re-organized these a bit.

ctalledo · rodnymolina · commit 614b2f73a962 · 2020-07-07T16:58:58.000-07:00
diff --git a/README.md b/README.md
@@ -10,7 +10,6 @@
 -   [Host Requirements](#host-requirements)
 -   [Installation](#installation)
 -   [Launching a System Container](#launching-a-system-container)
--   [Shiftfs](#shiftfs)
 -   [Sysbox Features](#sysbox-features)
 -   [Documentation](#documentation)
 -   [Integration with Container Managers](#integration-with-container-managers)
@@ -102,7 +101,9 @@ $ sha256sum sysbox_0.1.3-0.ubuntu-disco_amd64.deb
 774aa1442c9142a1e6c6db49f896439b989de3668926bccd91aa0a679fa3df87  sysbox_0.1.3-0.ubuntu-disco_amd64.deb
 ```
 
-3) Install the Sysbox package:
+3) Stop all running Docker containers (as the installer may need to restart Docker).
+
+4) Install the Sysbox package and follow the installer instructions:
 
 ```console
 $ sudo dpkg -i sysbox_0.1.3-0.ubuntu-disco_amd64.deb
@@ -118,7 +119,7 @@ $ sudo apt-get install -f -y
 This will install the missing dependencies and automatically re-launch
 the Sysbox installation process.
 
-4) Verify that Sysbox's Systemd units have been properly installed, and
+5) Verify that Sysbox's Systemd units have been properly installed, and
    associated daemons are properly running:
 
 ```console
@@ -131,9 +132,7 @@ sysbox.service                     loaded    active   exited  Sysbox General Ser
 Note: the sysbox.service is ephemeral (it exits once it launches the other sysbox services; that's why
 you see `sysbox.service   loaded  active  exited` above).
 
-If you are curious on what the other Sysbox services are, refer to the [Sysbox User Guide](docs/user-guide/design.md).
-
-If you hit problems during installation, see the [Troubleshooting doc](docs/user-guide/troubleshoot.md).
+See [here](docs/user-guide/install.md) for more info.
 
 ## Launching a System Container
 
@@ -157,20 +156,6 @@ regular Docker containers; they won't conflict and can co-exist side-by-side.
 The [Sysbox Quickstart Guide](docs/quickstart/README.md) and the [Nestybox Blog Site](https://blog.nestybox.com) have
 many usage examples.
 
-## Shiftfs
-
-Recent Ubuntu kernels carry a module called "shiftfs" that Sysbox uses to create
-the system containers.
-
-When launching the system container, if you see an error such as:
-
-    docker: Error response from daemon: OCI runtime create failed: container requires user-ID shifting but error was found: shiftfs module is not loaded in the kernel. Update your kernel to include shiftfs module or enable Docker with userns-remap. Refer to the Sysbox troubleshooting guide for more info: unknown
-
-it means that your kernel version is a bit older than needed by Sysbox.
-
-You can work-around this by enabling the "userns-remap mode" in Docker. Refer to
-the [distro compatibility doc](docs/distro-compat.md) for more info.
-
 ## Sysbox Features
 
 ### Integrates with Docker
diff --git a/docs/distro-compat.md b/docs/distro-compat.md
@@ -13,83 +13,19 @@ on adding support for more distros.
 
 ## Ubuntu Support
 
-Sysbox requires very recent Ubuntu versions:
+Sysbox requires recent Ubuntu versions:
 
 -   Ubuntu 20.04 "Focal Fossa"
 -   Ubuntu 19.10 "Eoan Ermine"
 -   Ubuntu 18.04 "Bionic Beaver" (with kernel upgrade >= 5.0)
 
-These versions carry some new Linux kernel features, including a module called
-"shiftfs", which Sysbox uses to create the system containers.
+These versions carry some new Linux kernel features that Sysbox relies on to
+create the system containers.
 
-If your Ubuntu version does not carry the shiftfs module, you'll see this error
-when launching a container:
-
-```console
-# docker run --runtime=sysbox-runc -it debian:latest
-docker: Error response from daemon: OCI runtime create failed: container requires user-ID shifting but error was found: shiftfs module is not loaded in the kernel. Update your kernel to include shiftfs module or enable Docker with userns-remap. Refer to the Sysbox troubleshooting guide for more info: unknown
-```
-
-Don't worry: you can still use Sysbox, but it requires that you configure Docker
-with "userns-remap" (see the next section).
-
-**NOTES:**
-
-1) Canonical generates Ubuntu editions for desktop, server, and cloud VMs. The
-[cloud editions](https://cloud-images.ubuntu.com/) may not carry the the shiftfs
-module. If you want to use Sysbox on a cloud VM and you hit the error shown
-above, you must either configure Docker with userns-remap as shown in the next
-section, or install the Ubuntu desktop or server edition in the VM.
-
-2) If you have a Ubuntu 18.04 (Bionic Beaver), you need to upgrade the kernel to >= 5.0.
+**NOTE:** If you have Ubuntu 18.04 (Bionic Beaver), you need to upgrade the kernel to >= 5.0.
 We recommend using Ubuntu's [LTS-enablement](https://wiki.ubuntu.com/Kernel/LTSEnablementStack)
-package to do the upgrade:
+package to do the upgrade as follows:
 
 ```console
 $ sudo apt-get update && sudo apt install --install-recommends linux-generic-hwe-18.04 -y
 ```
-
-### Using Sysbox on kernels without the shiftfs module
-
-If your Ubuntu version does not carry the shiftfs module, using Sysbox requires
-that you configure Docker in "userns-remap" mode.
-
-This is done by modifying the configuration of the Docker daemon and restarting it:
-
--   After installing Sysbox, add the `userns-remap` line to the
-    `/etc/docker/daemon.json` file as shown below:
-
-    ```console
-    # cat /etc/docker/daemon.json
-    {
-      "userns-remap": "sysbox",
-      "runtimes": {
-        "sysbox-runc": {
-          "path": "/usr/local/sbin/sysbox-runc"
-        }
-      }
-    }
-    ```
-
-    This tells Docker to use the Linux user namespace in all containers
-    and map the root user in the container to the subid range of
-    user `sysbox`, as defined in the `/etc/subuid` and `/etc/subgid` files.
-
--   Then restart the Docker daemon (make sure any running containers are stopped):
-
-    ```console
-    # sudo docker stop $(docker ps -aq)
-    # sudo systemctl restart docker.service
-    ```
-
-Note that the actions above require `root` privileges on the host.
-
-When Docker is configured this way, Sysbox no longer needs the shiftfs
-module. But there are a couple of drawbacks:
-
--   Configuring Docker this way places a few functional limitations on regular Docker containers
-    (those launched with Docker's default runc), as described in this [Docker document](https://docs.docker.com/engine/security/userns-remap).
-
--   System container isolation, while strong, is reduced compared to using shiftfs.
-    That's because userns-remap causes Docker to put Sysbox into "Directed Userns ID Mapping" mode.
-    See [here](user-guide/security.md#user-namespace-id-mapping) for more info on this.
diff --git a/docs/quickstart/README.md b/docs/quickstart/README.md
@@ -3,7 +3,7 @@
 This document shows, by way of example, how to deploy system containers and
 quickly take advantage of their features.
 
-It assumes you've [installed](../../README.md#supported-distros) Sysbox.
+It assumes you've [installed](../user-guide/install.md) Sysbox.
 
 For an in-depth description of Sysbox's functionality, refer to the [Sysbox Users Guide](../user-guide/README.md).
 
@@ -27,7 +27,7 @@ how to use system containers.
 ### Kubernetes-in-Docker
 
 -   [Why Sysbox for K8s-in-Docker?](kind.md#why-sysbox-for-k8s-in-docker)
--   [Using K8s.io KinD + Sysbox](kind.md#using-k8sio-kind--sysbox)
+-   [Using K8s.io KinD + Sysbox](kind.md#using-k8sio-kind--sysbox-kind-sysbox)
 -   [Using Kindbox](kind.md#using-kindbox)
 -   [Using Docker to Deploy a K8s Cluster](kind.md#using-docker-to-deploy-a-k8s-cluster)
 -   [Preloading Inner Pod Images into the K8s Node Image](kind.md#preloading-inner-pod-images-into-the-k8s-node-image)
diff --git a/docs/quickstart/dind.md b/docs/quickstart/dind.md
@@ -5,6 +5,14 @@ This section shows examples for running Docker inside system containers.
 The [User Guide](../user-guide/dind.md) describes this functionality in
 deeper detail.
 
+## Contents
+
+-   [Deploy a System Container with Docker inside](#deploy-a-system-container-with-docker-inside)
+-   [Deploy a System Container with Systemd, sshd, and Docker inside](#deploy-a-system-container-with-systemd-sshd-and-docker-inside)
+-   [Deploy a System Container with Supervisord and Docker inside](#deploy-a-system-container-with-supervisord-and-docker-inside)
+-   [Persistence of Inner Container Images using Docker Volumes](#persistence-of-inner-container-images-using-docker-volumes)
+-   [Persistence of Inner Container Images using Bind Mounts](#persistence-of-inner-container-images-using-bind-mounts)
+
 ## Deploy a System Container with Docker inside
 
 We will use a system container image that has Alpine + Docker inside. It's called
@@ -415,12 +423,12 @@ There are a couple of important caveats to keep in mind:
 -   A Docker volume mounted into the system container's `/var/lib/docker` must
     only be mounted on a **single system container at any given time**.
 
-    - This is a restriction imposed by the Docker daemon, which does not allow
-      its image cache to be shared concurrently among multiple daemon
-      instances.
+    -   This is a restriction imposed by the Docker daemon, which does not allow
+        its image cache to be shared concurrently among multiple daemon
+        instances.
 
-    - Sysbox will check for violations of this rule and report an
-      appropriate error during system container creation.
+    -   Sysbox will check for violations of this rule and report an
+        appropriate error during system container creation.
 
 -   A Docker volume mounted into the system container's `/var/lib/docker`
     will **inherit** any files present in that same directory as part of the system
diff --git a/docs/quickstart/kind.md b/docs/quickstart/kind.md
@@ -9,6 +9,14 @@ This section shows several examples on how to do this.
 The [User Guide](../user-guide/kind.md) describes this functionality in more
 detail.
 
+## Contents
+
+-   [Why Sysbox for K8s-in-Docker?](#why-sysbox-for-k8s-in-docker)
+-   [Using K8s.io KinD + Sysbox (kind-sysbox)](#using-k8sio-kind--sysbox-kind-sysbox)
+-   [Using Kindbox](#using-kindbox)
+-   [Using Docker to Deploy a K8s Cluster](#using-docker-to-deploy-a-k8s-cluster)
+-   [Preloading Inner Pod Images into the K8s Node Image](#preloading-inner-pod-images-into-the-k8s-node-image)
+
 ## Why Sysbox for K8s-in-Docker?
 
 Sysbox is the first container runtime capable of creating containers that can
@@ -30,15 +38,15 @@ Here is a comparison for deploying a 10-node K8s cluster:
 
 | Criteria                       | K8s.io KinD (w/o Sysbox) | K8s.io KinD (with Sysbox) | Kindbox |
 | ------------------------------ | :----------------------: | :-----------------------: | :-----: |
-| Host storage overhead          | 10 GB                    | 3 GB                      | 1 GB    |
-| Cluster creation time          | 2 min                    | 2 min                     | 2 min   |
-| Cluster deletion time          | 5 sec                    | 20 sec                    | 13 sec  |
-| Simple Docker images           | No                       | No                        | Yes     |
-| Full control of cluster config | No                       | No                        | Yes     |
-| Dynamically resize cluster     | No                       | No                        | Yes     |
-| Mixed cluster node images      | No                       | No                        | Yes     |
-| Easily preload inner images    | No                       | Yes                       | Yes     |
-| Strong isolation from host     | No                       | Yes                       | Yes     |
+| Host storage overhead          |           10 GB          |            3 GB           |   1 GB  |
+| Cluster creation time          |           2 min          |           2 min           |  2 min  |
+| Cluster deletion time          |           5 sec          |           20 sec          |  13 sec |
+| Simple Docker images           |            No            |             No            |   Yes   |
+| Full control of cluster config |            No            |             No            |   Yes   |
+| Dynamically resize cluster     |            No            |             No            |   Yes   |
+| Mixed cluster node images      |            No            |             No            |   Yes   |
+| Easily preload inner images    |            No            |            Yes            |   Yes   |
+| Strong isolation from host     |            No            |            Yes            |   Yes   |
 
 The sections below show examples of this.
 
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
@@ -13,6 +13,8 @@ functionality.
 
 [Concepts & Terminology](concepts.md)
 
+[Installing Sysbox](install.md)
+
 [Deploying System Containers](deploy.md)
 
 [Docker-in-Docker](dind.md)
diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md
diff --git a/docs/user-guide/kind.md b/docs/user-guide/kind.md
diff --git a/docs/user-guide/troubleshoot.md b/docs/user-guide/troubleshoot.md
