diff --git a/README.md b/README.md
index db82520f0..fa33d700d 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,53 @@ Basic proof of 'ipfs working' locally:
 	ipfs cat <that hash>
 
 
+### Docker usage
+
+An ipfs docker image is hosted at [hub.docker.com/u/ipfs/go-ipfs](hub.docker.com/u/ipfs/go-ipfs).
+To make files visible inside the container you need to mount a host directory 
+with the `-v` option to docker. Choose a directory that you want to use to
+import/export files from ipfs. You should also choose a directory to store 
+ipfs files that will persist when you restart the container.
+
+    export ipfs_staging=</absolute/path/to/somewhere/>
+    export ipfs_data=</absolute/path/to/somewhere_else/>
+    
+Start a container running ipfs and expose ports 4001, 5001 and 8080:
+
+    docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/root/.go-ipfs -p 8080:8080 -p 4001:4001 -p 5001:5001 jbenet/go-ipfs:latest
+    
+Wait for ipfs to start. ipfs is running when you see: 
+
+    Gateway (readonly) server 
+    listening on /ip4/0.0.0.0/tcp/8080" in the container logs (`docker logs -f ipfs_host`)
+
+Run ipfs commands:
+
+    docker exec ipfs_host ipfs <args...>
+
+For example: connect to peers
+    
+    docker exec ipfs_host ipfs swarm peers
+    
+
+Add files:
+
+    cp -r <something> $ipfs_staging
+    docker exec ipfs_host ipfs add -r /export/<something>
+    
+Stop the running container:
+
+    docker stop ipfs_host
+    
+#### Docker usage with VirtualBox/boot2docker (OSX and Windows)
+
+Since docker is running in the boot2docker VM, you need to forward 
+relevant ports from the VM to your host for ipfs act normally. This is 
+accomplished with the following command:
+
+    boot2docker ssh -L 5001:localhost:5001 -L 4001:localhost:4001 -L 8080:localhost:8080 -fN
+
+
 ### Troubleshooting
 If you have previously installed ipfs before and you are running into
 problems getting a newer version to work, try deleting (or backing up somewhere