docs: add section for containers

Starting with how to containerize an SPDK app for Docker by example.

Signed-off-by: paul luse <paul.e.luse@intel.com>
Change-Id: Ice2cbf0ab54f2c541e38508a133a7ef0f23dd40e
Reviewed-on: https://review.gerrithub.io/c/spdk/spdk/+/479900
Reviewed-by: Jim Harris <james.r.harris@intel.com>
Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com>
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>

doc/Doxyfile

@@ -809,6 +809,7 @@ INPUT                  += \
                          changelog.md \
                          compression.md \
                          concurrency.md \
+                         containers.md \
                          event.md \
                          ftl.md \
                          gdb_macros.md \

doc/containers.md

@@ -0,0 +1,76 @@
+# SPDK and Containers {#containers}
+
+This is a living document as there are many ways to use containers with
+SPDK. As new usages are identified and tested, they will be documented
+here.
+
+# In this document {#containers_toc}
+
+* @ref spdk_in_docker
+
+# Containerizing an SPDK Application for Docker {#spdk_in_docker}
+
+There are no SPDK specific changes needed to run an SPDK based application in
+a docker container, however this quick start guide should help you as you
+containerize your SPDK based application.
+
+1. Make sure you have all of your app dependencies identified and included in your Dockerfile
+2. Make sure you have compiled your application for the target arch
+3. Make sure your host has hugepages enabled
+4. Make sure your host has bound your nvme device to your userspace driver
+5. Write your Dockerfile. The following is a simple Dockerfile to containerize the nvme `hello_world`
+example:
+
+~~~{.sh}
+# start with the latest Fedora
+FROM fedora
+
+# if you are behind a proxy, set that up now
+ADD dnf.conf /etc/dnf/dnf.conf
+
+# these are the min dependencies for the hello_world app
+RUN dnf install libaio-devel -y
+RUN dnf install numactl-devel -y
+
+# set our working dir
+WORKDIR /app
+
+# add the hello_world binary
+ADD hello_world hello_world
+
+# run the app
+CMD ./hello_world
+~~~
+
+6. Create your image
+
+`sudo docker image build -t hello:1.0 .`
+
+7. You docker command line will need to include at least the following:
+- the `--privileged` flag to enable sharing of hugepages
+- use of the `-v` switch to map hugepages
+
+`sudo docker run --privileged -v /dev/hugepages:/dev/hugepages hello:1.0`
+
+or depending on the needs of your app you may need one or more of the following parameters:
+
+- If you are using the SPDK app framework: `-v /dev/shm:/dev/shm`
+- If you need to use RPCs from outside of the container: `-v /var/tmp:/var/tmp`
+- If you need to use the host network (i.e. NVMF target application): `--network host`
+
+Your output should look something like this:
+
+~~~{.sh}
+$ sudo docker run --privileged -v //dev//hugepages://dev//hugepages hello:1.0
+Starting SPDK v20.01-pre git sha1 80da95481 // DPDK 19.11.0 initialization...
+[ DPDK EAL parameters: hello_world -c 0x1 --log-level=lib.eal:6 --log-level=lib.cryptodev:5 --log-level=user1:6 --iova-mode=pa --base-virtaddr=0x200000000000 --match-allocations --file-prefix=spdk0 --proc-type=auto ]
+EAL: No available hugepages reported in hugepages-1048576kB
+Initializing NVMe Controllers
+Attaching to 0000:06:00.0
+Attached to 0000:06:00.0
+Using controller INTEL SSDPEDMD400G4  (CVFT7203005M400LGN  ) with 1 namespaces.
+  Namespace ID: 1 size: 400GB
+Initialization complete.
+INFO: using host memory buffer for IO
+Hello world!
+~~~

doc/misc.md

@@ -1,3 +1,4 @@
 # Miscellaneous {#misc}
 
 - @subpage peer_2_peer
+- @subpage containers