From 87dcedb817c88f126339bfd564398a87cf9805b2 Mon Sep 17 00:00:00 2001
From: paul luse <paul.e.luse@intel.com>
Date: Thu, 9 Jan 2020 20:57:10 +0000
Subject: [PATCH] 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      |  1 +
 doc/containers.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/misc.md       |  1 +
 3 files changed, 78 insertions(+)
 create mode 100644 doc/containers.md

diff --git a/doc/Doxyfile b/doc/Doxyfile
index ef82a8944..d62b3a8c8 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -809,6 +809,7 @@ INPUT                  += \
                          changelog.md \
                          compression.md \
                          concurrency.md \
+                         containers.md \
                          event.md \
                          ftl.md \
                          gdb_macros.md \
diff --git a/doc/containers.md b/doc/containers.md
new file mode 100644
index 000000000..c8de93eb0
--- /dev/null
+++ b/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!
+~~~
diff --git a/doc/misc.md b/doc/misc.md
index 7eb22354b..a290afe94 100644
--- a/doc/misc.md
+++ b/doc/misc.md
@@ -1,3 +1,4 @@
 # Miscellaneous {#misc}
 
 - @subpage peer_2_peer
+- @subpage containers