Updates to Neo4j documentation

neo4j/README-short.txt

@@ -1 +1 @@
-Neo4j is an highly scalable, robust (fully ACID) native graph database.
+Neo4j is a highly scalable, robust native graph database.

neo4j/content.md

@@ -6,25 +6,29 @@ Neo4j is a highly scalable, robust, native graph database. It is used in mission
 
 # How to use this image
 
+*NOTE:* Docker does not run natively on OSX or Windows. If you are running on one of these platforms you will need to run Docker inside a VM. Please read the Docker documentation for your platform ([OSX](http://docs.docker.com/engine/installation/mac/), [Windows](http://docs.docker.com/engine/installation/windows/)). The instructions below include variants to cope with the difference between platforms where necessary; they assume that on OSX you have a shell set up as per the instructions linked above and that you have a Docker machine VM called `default`.
+
 The image exposes two ports (`7474` and `7473`) for HTTP and HTTPS access to the Neo4j API and a volume (`/data`) to allow the database to be persisted outside its container.
 
 	docker run \
 	    --detach \
 	    --publish=7474:7474 \
-	    --volume=$HOME/neo4j-data:/data \
+	    --volume=$HOME/neo4j/data:/data \
 	    neo4j
 
-Point your browser at `http://localhost:7474`.
+Point your browser at `http://localhost:7474` on Linux or `http://$(docker-machine ip default):7474` on OSX.
+
+*NOTE:* All the volumes in this guide are stored under `$HOME` in order to work on OSX where `$HOME` is automatically mounted into the machine VM. On Linux the volumes can be stored anywhere.
 
-Please note that by default Neo4j requires authentication. You have to login with `neo4j/neo4j` at the first connection and set a new password.
+*NOTE:* By default Neo4j requires authentication. You have to login with `neo4j/neo4j` at the first connection and set a new password.
 
 ## Neo4j editions
 
 The Neo4j comes in two editions: Community and Enterprise.
 
 Neo4j Enterprise Edition is designed for commercial deployments where scale and availability are important. Use of Neo4j Enterprise Edition requires a commercial license agreement with Neo Technology. Please see [Neo4j licensing](http://neo4j.com/licensing/) for details.
 
-Tags are available for both editions. Enterprise tags have an `-enterprise` suffix, Community tags have no suffix.
+Tags are available for both editions. Version-specific Enterprise tags have an `-enterprise` suffix (like `neo4j:2.3.0-enterprise`), Community tags have no suffix (like `neo4j:2.3.0`). The latest Enterprise release is available as `neo4j:enterprise`.
 
 ## Docker configuration
 
@@ -44,13 +48,13 @@ To override the default configuration for a single container, use the `--ulimit`
 	docker run \
 	    --detach \
 	    --publish=7474:7474 \
-	    --volume=$HOME/neo4j-data:/data \
+	    --volume=$HOME/neo4j/data:/data \
 	    --ulimit=nofile=40000:40000
 	    neo4j
 
 ## Neo4j configuration
 
-The image provides a usable default configuration for learning about Neo4j, but it is not suitable for production use. You can read more about configuring Neo4j in the [manual](http://neo4j.com/docs/stable/configuration.html).
+The default configuration provided by this image is intended for learning about Neo4j, but must be modified to make it suitable for production use. In particular the memory assigned to Neo4j is very limited (see `NEO4J_CACHE_MEMORY` and `NEO4J_HEAP_MEMORY` below), to allow multiple containers to be run on the same server. You can read more about configuring Neo4j in the [manual](http://neo4j.com/docs/stable/configuration.html).
 
 There are three ways to modify the configuration depending on how much you need to customize the image.
 
@@ -61,14 +65,14 @@ Pass environment variables to the container when you run it.
 	docker run \
 	    --detach \
 	    --publish=7474:7474 \
-	    --volume=$HOME/neo4j-data:/data \
+	    --volume=$HOME/neo4j/data:/data \
 	    --env=NEO4J_CACHE_MEMORY=4G \
 	    neo4j
 
 The following environment variables are available:
 
 -	`NEO4J_CACHE_MEMORY`: the size of Neo4j's native-memory cache, defaults to 512M
--	`NEO4J_HEAP_MEMORY`: the size of Neo4j's heap in MB, defaults to the JVM default for your system
+-	`NEO4J_HEAP_MEMORY`: the size of Neo4j's heap in MB, defaults to 512
 -	`NEO4J_KEEP_LOGICAL_LOGS`: the retention policy for logical logs, defaults to `100M size`
 -	`NEO4J_AUTH`: controls authentication, set to `none` to disable authentication or `neo4j/<password>` to override the default password (see documentation [here](http://neo4j.com/docs/stable/rest-api-security.html))
 -	`NEO4J_THIRDPARTY_JAXRS_CLASSES`: URI mappings for unmanaged extensions (see below)
@@ -89,16 +93,16 @@ To make arbitrary modifications to the Neo4j configuration, provide the containe
 	docker run \
 	    --detach \
 	    --publish=7474:7474 \
-	    --volume=$HOME/neo4j-data:/data \
-	    --volume=$HOME/neo4j-conf:/conf \
+	    --volume=$HOME/neo4j/data:/data \
+	    --volume=$HOME/neo4j/conf:/conf \
 	    neo4j
 
-The `/conf` volume will override all configuration provided by the image and must therefore contain a complete, valid set of Neo4j configuration files.
+Any configuration files in the `/conf` volume will override files provided by the image. This includes values that may have been set in response to environment variables passed to the container by Docker. So if you want to change one value in a file you must ensure that the rest of the file is complete and correct.
 
-To generate an initial set of configuration files, run the image with the `dump-config` command.
+To dump an initial set of configuration files, run the image with the `dump-config` command.
 
 	docker run --rm\
-	    --volume=$HOME/neo4j-conf:/conf \
+	    --volume=$HOME/neo4j/conf:/conf \
 	    neo4j dump-config
 
 ### Build a new image
@@ -113,21 +117,21 @@ For more complex customization of the image you can create a new image based on
 
 In order to run Neo4j in HA mode under Docker you need to wire up the containers in the cluster so that they can talk to each other. Each container must have a network route to each of the others and the `NEO4J_HA_ADDRESS` and `NEO4J_INITIAL_HOSTS` environment variables must be set according (see above).
 
-Within a single Docker host, this can be achieved using container names and links as follows.
+Within a single Docker host, this can be achieved as follows.
 
-	docker run --name=instance1 --detach --publish 7474:7474 \
+	docker network create --driver=bridge cluster
+
+	docker run --name=instance1 --detach --publish=7474:7474 --net=cluster --hostname=instance1 \
 	    --env=NEO4J_DATABASE_MODE=HA --env=NEO4J_HA_ADDRESS=instance1 --env=NEO4J_SERVER_ID=1 \
 	    --env=NEO4J_INITIAL_HOSTS=instance1:5001,instance2:5001,instance3:5001 \
 	    neo4j:enterprise
 
-	docker run --name=instance2 --detach --publish 7475:7474 \
-	    --link instance1:instance1 \
+	docker run --name=instance2 --detach --publish 7475:7474 --net=cluster --hostname=instance2 \
 	    --env=NEO4J_DATABASE_MODE=HA --env=NEO4J_HA_ADDRESS=instance2 --env=NEO4J_SERVER_ID=2 \
 	    --env=NEO4J_INITIAL_HOSTS=instance1:5001,instance2:5001,instance3:5001 \
 	    neo4j:enterprise
 
-	docker run --name=instance3 --detach --publish 7476:7474 \
-	    --link instance1:instance1 --link instance2:instance2 \
+	docker run --name=instance3 --detach --publish 7476:7474 --net=cluster --hostname=instance3 \
 	    --env=NEO4J_DATABASE_MODE=HA --env=NEO4J_HA_ADDRESS=instance3 --env=NEO4J_SERVER_ID=3 \
 	    --env=NEO4J_INITIAL_HOSTS=instance1:5001,instance2:5001,instance3:5001 \
 	    neo4j:enterprise
@@ -136,7 +140,7 @@ Within a single Docker host, this can be achieved using container names and link
 
 To install a plugin or unmanaged extension, provide a `/plugins` volume containing the jars. For unmanged extensions you also need to provide an environment variable specifying a URI mapping.
 
-	docker run --publish 7474:7474 --volume=/tmp/neo4j-plugins:/plugins \
+	docker run --publish 7474:7474 --volume=$HOME/neo4j/plugins:/plugins \
 	    --env=NEO4J_THIRDPARTY_JAXRS_CLASSES=com.example.extension=/example
 	    neo4j