Updated sysbox docs regarding lack of support for Docker snap pkg.

Author: ctalledo

README.md

@@ -85,7 +85,7 @@ The Linux host on which Sysbox runs must meet the following requirements:
 
 2) Systemd must be the system's process-manager (the default in the supported distros).
 
-3) Docker must be installed.
+3) Docker must be [installed natively](docs/user-guide/install.md#docker-installation) (**not** with the Docker snap package).
 
 ## Installation
 
@@ -274,8 +274,8 @@ The [K8s.io KinD](https://kind.sigs.k8s.io) project produces a CLI tool called
 It's an excellent tool that makes deployment of K8s cluster in containers fast &
 easy.
 
-When used with the Sysbox container runtime, the capabilities of the "kind" tool
-are enhanced:
+Sysbox complements this tool. When used with the Sysbox container runtime, the
+capabilities of the "kind" tool are enhanced:
 
 -   The containerized K8s clusters consume **significantly less host
     storage** (70% reduction for a 10-node cluster!).
@@ -285,7 +285,7 @@ are enhanced:
 -   You can use Sysbox to **easily** embed inner pod images into the K8s nodes.
 
 Moreover, with Sysbox, you can easily create a containerized K8s cluster without
-using the K8s.io kind tool, by using very simple Docker images and Docker run
+using the K8s.io KinD tool, by using very simple Docker images and Docker run
 commands.
 
 We've created a tool called "kindbox" that is a simple wrapper around Docker
@@ -295,7 +295,7 @@ This results in simple images and gives you full control of the
 cluster configuration. The Sysbox runtime does the heavy lifting of ensuring
 that K8s runs seamlessly inside the containers.
 
-The Sysbox [user-guide](docs/user-guide/kind.md) has more on this.
+The Sysbox [quickstart-guide](docs/quickstart/kind.md) and [user-guide](docs/user-guide/kind.md) have more on this.
 
 ## Troubleshooting
 

docs/quickstart/kind.md

@@ -803,6 +803,11 @@ K8s.io KinD + Sysbox).
    required during the image build process (i.e, you can revert the config
    once the build completes if you wish).
 
+NOTE: if using the Ubuntu Docker snap package, edit the
+`/var/snap/docker/current/etc/docker/daemon.json` file instead of
+`/etc/docker/daemon.json` below. You can tell if you are using the Docker
+snap package if `which docker` yields `/snap/bin/docker`.
+
 ```console
 # more /etc/docker/daemon.json
 {
@@ -817,6 +822,9 @@ K8s.io KinD + Sysbox).
 
 2) Stop all containers and restart the Docker service:
 
+NOTE: if using the Ubuntu Docker snap package, do `$ sudo snap restart docker`
+instead of `systemctl restart docker.service` below.
+
 ```console
 $ docker stop $(docker ps -aq)
 $ sudo systemctl restart docker.service

docs/user-guide/install.md

@@ -2,22 +2,25 @@
 
 ## Contents
 
+-   [Host Requirements](#host-requirements)
 -   [Installing Sysbox](#installing-sysbox)
 -   [Uninstalling Sysbox](#uninstalling-sysbox)
+-   [Docker Installation](#docker-installation)
 
-## Installing Sysbox
-
-### Host Requirements
+## Host Requirements
 
 The Linux host on which Sysbox runs must meet the following requirements:
 
 1) It must have one of the [supported Linux distros](../distro-compat.md).
 
 2) Systemd must be the system's process-manager (the default in the supported distros).
 
-3) Docker must be installed.
+3) Docker must be installed natively (i.e., **not** with the Docker snap package).
 
-### Installation Steps
+-   See [below](#docker-installation) if you have a Docker snap installation and
+    need to change it to a native installation.
+
+## Installing Sysbox
 
 1) Download the latest Sysbox package from the [release](https://github.com/nestybox/sysbox-external/releases) page.
 
@@ -64,7 +67,7 @@ If you are curious on what the other Sysbox services are, refer to the [design s
 
 If you hit problems during installation, see the [Troubleshooting doc](troubleshoot.md).
 
-### Docker Configuration
+### Docker Runtime Configuration
 
 During installation, the Sysbox installer will reconfigure the Docker daemon such
 that it detects the Sysbox runtime. It does this by adding the following
@@ -80,6 +83,15 @@ configuration to `/etc/docker/daemon.json` and sending a signal (SIGHUP) to Dock
 }
 ```
 
+If all is well, Docker will recognize the Sysbox runtime:
+
+```console
+$ docker info | grep -i runtime
+WARNING: No swap limit support
+ Runtimes: runc sysbox-runc
+  Default Runtime: runc
+```
+
 ### Docker Userns-Remap
 
 In addition, the Sysbox installer will detect if Docker needs to be placed
@@ -114,16 +126,16 @@ Otherwise, the Sysbox installer will add the following `userns-remap` entry to t
 }
 ```
 
-The installer will then ask the user if Docker should be restarted. If
-the user responds affirmatively, the installer will restart Docker. Otherwise,
-the user will need to restart Docker manually (e.g., `systemctl restart docker`)
-before using Sysbox.
+The installer will then ask the user if Docker should be restarted. If the user
+responds affirmatively, the installer will restart Docker
+automatically. Otherwise, the user will need to restart Docker manually (e.g.,
+`systemctl restart docker`) before using Sysbox.
 
 When Docker is placed in userns-remap mode, there are a couple of caveats to
 keep in mind:
 
 -   Configuring Docker this way places a few functional limitations on regular
-    Docker containers (those launched with Docker's default runc), as described
+    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
@@ -154,3 +166,89 @@ $ sudo dpkg --purge sysbox
 ```console
 $ sudo userdel sysbox
 ```
+
+## Docker Installation
+
+Ubuntu offers two methods for installing Docker:
+
+1) Via `apt get` (aka native installation)
+
+2) Via `snap install` (aka snappy installation)
+
+In recent versions of Ubuntu, (2) is the default approach. For example, while installing
+Ubuntu Focal on a VM, the installer will ask if you want to install Docker. If you answer
+"yes", it will use the snappy installation method.
+
+You can tell if Docker is installed via a snap by doing:
+
+```console
+$ which docker
+/snap/bin/docker
+```
+
+Unfortunately, Sysbox **does not currently support** working with Docker when the latter is
+installed via a snap package. We are working on resolving this.
+
+In the meantime, you **must install Docker natively** (method (1) above).
+
+These are the steps to do so:
+
+1) If Docker is installed via a snap, remove the snap:
+
+```console
+$ sudo snap remove docker
+docker removed
+```
+
+2) Install Docker natively.
+
+Follow the instructions in this [Docker doc](https://docs.docker.com/engine/install/ubuntu/).
+
+3) Confirm Docker is installed natively:
+
+```console
+$ which docker
+/usr/bin/docker
+```
+
+4) Make sure you are in the `docker` group:
+
+```console
+$ sudo usermod -a -G docker $(whoami)
+```
+
+You may need to log-out and log-in for the group setting to take effect.
+
+If you are not in the `docker` group (or have no sudo privileges), you'll see an error such as:
+
+```console
+$ docker run -it alpine
+Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: ... connect: permission denied
+```
+
+5) Verify Docker works:
+
+```console
+$ docker run -it alpine
+Unable to find image 'alpine:latest' locally
+latest: Pulling from library/alpine
+df20fa9351a1: Pull complete
+Digest: sha256:185518070891758909c9f839cf4ca393ee977ac378609f700f60a771a2dfe321
+Status: Downloaded newer image for alpine:latest
+/ #
+```
+
+At this point you have Docker working, and can now [install Sysbox](#installing-sysbox).
+
+If you want to revert back to the Docker snap, the steps are below, but keep in
+mind that Sysbox **won't work**.
+
+1) Uninstall the native Docker
+
+See [here](https://docs.docker.com/engine/install/ubuntu/#uninstall-old-versions).
+
+2) Re-install the Docker snap:
+
+```console
+$ sudo snap install docker
+```

docs/user-guide/security.md

@@ -220,8 +220,8 @@ Sysbox will check for this. If the module is required but not present in the
 Linux kernel, Sysbox will fail to launch containers and issue an error such as
 [this one](troubleshoot.md#ubuntu-shiftfs-module-not-present).
 
-Note that shiftfs is not present in all Ubuntu kernels. See
-[here](../distro-compat.md) for more info.
+Note that shiftfs is present in Ubuntu Desktop and Server editions, but likely
+not present in Ubuntu cloud editions.
 
 ## Procfs Virtualization