Document docker work

docs/src/recipes/docker.md

@@ -0,0 +1,52 @@
+# Docker
+
+This is work-in-progress integration with Docker for Scone.
+
+For this set of recipes to work, you will need the sous to have the `docker`
+Python package installed; for this, you can use `pip install docker` with the
+scone virtualenv activated. (TODO link to better documentation about installing
+other Python deps in a scone venv.)
+
+| Recipe | Needs | Provides |
+| -----: | ----- | -------- |
+| [`docker-container`](#docker-container) | | `docker_container` |
+
+## `docker-container`
+
+**Preconditions**: the image must be available or downloadable
+
+**Provides**: `docker-container(?)` where `?` is the argument `name`.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| image | any Docker image that exists or can be pulled | *required* | This name is used to specify what image to install. |
+| name | any ID string | *required* | This name identifies the container and is passed to docker. |
+| command | any command string | *optional* | If specified, this sets the command that will be run by the container. |
+| ports | dictionary of "(container port)/tcp" or "(container port)/udp" to {host = "(host address)", port = "(host port)"} | empty | This mapping describes how ports are published from inside the container to the host. |
+| volumes | dictionary of "(volume name)" or "/path/to/binding/on/host" to {bind = "/path/in/container", mode = "rw" or "ro"} | empty | This mapping describes what filesystem resources are mounted into the container. |
+| environment | dictionary of "(key)" to value | empty | This mapping describes what environment variables are given to the container. |
+| restart_policy | "always" or "on-failure" | "on-failure" | This specifies the container's restart policy. |
+
+### Example
+
+```scoml
+[[docker-container]]
+image = "org/image:1"
+name = "mycontainer"
+ports = {
+  "80/tcp" = {
+    "host" = "127.0.0.1",
+    "port" = 4080
+  }
+}
+volumes = {
+  "/var/lib/mycontainer" = {
+    bind = "/data",
+    mode = "rw"
+  }
+}
+environment = {
+  MYCONTAINER_MODE = "production"
+}
+restart_policy = "always"
+```