Merge pull request #16 from surgeforward/4-readme

Update README and other cleanup

.dockerignore

@@ -8,3 +8,5 @@ hack
 *.iml
 coverage.out
 *_test.go
+*.md
+LICENSE

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Cameron Spear
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,5 +1,59 @@
 # Local Persist Volume Plugin for Docker
 
-[ ![Codeship Status for CWSpear/docker-local-persist-volume-plugin](https://codeship.com/projects/5b4fe7d0-b03c-0133-b8cb-5205290a2fee/status?branch=master)](https://codeship.com/projects/132639)
+[![Build Status](https://travis-ci.org/CWSpear/docker-local-persist-volume-plugin.svg?branch=master)](https://travis-ci.org/CWSpear/docker-local-persist-volume-plugin)
+
+Create named local volumes that persist in the location(s) you want!
+
+## Rationale 
+
+In Docker 1.9, they added support for [creating standalone named Volumes](https://docs.docker.com/engine/reference/commandline/volume_create/). Now with Docker 1.10 and Docker Compose 1.6's new syntax, you can [create named volumes through Docker Compose](https://docs.docker.com/compose/compose-file/#volume-configuration-reference:91de898b5f5cdb090642a917d3dedf68).
+
+ This is great for creating standalone volumes and easily connecting them to different directories in different containers as a way to share data between multiple containers. On a much larger scale, it also allows for the use of Docker Volume Plugins to do cool things like [Flocker](https://github.com/ClusterHQ/flocker) is doing (help run stateful containers across multiple hosts).
+
+If something like Flocker is overkill for your needs, it can still be useful for
+
+## Installing & Running
+
+To create a Docker Plugin, one must create a Unix socket that Docker will look for when you use the plugin and then it listens for commands from Docker and runs the corresponding code when necessary.
+
+Running the code in this project with create the said socket, listening for commands from Docker to create the necessary Volumes.
+
+Pre-1.0, you can either build and run the project locally, or use this with Docker (run this on your Docker host):
+
+```shell
+docker run -d \
+    -v /run/docker/plugins/:/run/docker/plugins/ \
+    -v /path/to/where/you/want/data/volume/:/path/to/where/you/want/data/volume/ \ 
+        cwspear/docker-local-persist-volume-plugin
+```
+
+The `-v /run/docker/plugins/:/run/docker/plugins/` part will make sure the `sock` file gets created at the right place. You also need to add one or more volumes to places you want to mount your volumes later at.
+
+For example, if I am going to persist my MySQL data for a container I'm going to build later at `/data/mysql/`, I would add a `-v /data/mysql/:/data/mysql/` to the command above (or even `-v /data/:/data/`).
+
+## Usage
+
+Then to use, you can create a volume with this plugin (this example will be for a shared folder for images):
+
+```shell
+docker create volume create -d local-persist -o mountpoint=/data/images --name=images
+```
+
+Then if you create a container, you can connect it to this Volume:
+
+```shell
+docker run -d -v images:/path/to/images/on/one/ one
+docker run -d -v images:/path/to/images/on/two/ two
+# etc
+```
+
+Also, see [docker-compose.example.yml](https://github.com/CWSpear/docker-local-persist-volume-plugin/blob/master/docker-compose.example.yml) for an example to do something like this with Docker Compose (needs Compose 1.6+ and Engine 1.10+).
+
+## Benefits
+
+This has a few advantages over the (default) `local` driver that comes with Docker, because our data *will not be deleted* when the Volume is removed. The `local` driver deletes all data when it's removed. With the `local-persist` driver, if you remove the driver, and then recreate it later with the same command above, any volume that was added to that volume will *still be there*.
+
+You may have noticed that you could do this with data-only containers, too. And that's true, and using that technique has a few advantages, one thing it (specifically as a limitation of `volumes-from`) does *not* allow, is mounting that shared volume to a different path inside your containers. Trying to recreate the above example, each container would have to store images in the same directory in their containers, instead of separate ones which `local-persist` allows.
+
+Also, using `local-persist` instead of data-only containers, `docker ps -a` won't have extra dead entries, and `docker volume ls` will have more descriptive output (because volumes have names).
 
-More README coming soon

test.yml → docker-compose.example.yml

@@ -4,16 +4,14 @@ services:
   one:
     image: debian:jessie
     working_dir: /one/
-    command: top
-    tty: true
+    command: sleep 600
     volumes:
       - data:/one/
 
   two:
     image: debian:jessie
     working_dir: /two/
-    command: top
-    tty: true
+    command: sleep 600
     volumes:
       - data:/two/
 

hack/docker-run.sh

@@ -5,7 +5,7 @@ if [[ ! -e $DATA_VOLUME ]]; then
     exit 1
 fi
 
-CMD="docker run -d -v /run/docker/plugins/:/run/docker/plugins/ -v ${DATA_VOLUME}:${DATA_VOLUME} --restart always cwspear/docker-local-persist-volume-plugin"
+CMD="docker run -d -v /run/docker/plugins/:/run/docker/plugins/ -v ${DATA_VOLUME}:${DATA_VOLUME} cwspear/docker-local-persist-volume-plugin"
 
 echo $CMD
 exec $CMD