Add missing content to the Docker docs (#1804)

modules/ROOT/content-nav.adoc

@@ -21,7 +21,10 @@
 
 * xref:docker/index.adoc[]
 ** xref:docker/introduction.adoc[]
+** xref:docker/mounting-volumes.adoc[]
 ** xref:docker/configuration.adoc[]
+** xref:docker/plugins.adoc[]
+** xref:docker/docker-compose-standalone.adoc[]
 ** xref:docker/clustering.adoc[]
 ** xref:docker/operations.adoc[]
 ** xref:docker/security.adoc[]

modules/ROOT/pages/docker/clustering.adoc

@@ -1,7 +1,7 @@
 [role=enterprise-edition]
 [[docker-cc]]
-= Clustering
-:description: How to deploy a Causal Cluster setup in a containerized environment without an orchestration tool. 
+= Deploy a Neo4j cluster on Docker
+:description: How to deploy a Causal Cluster setup in a containerized environment without an orchestration tool.
 
 [NOTE]
 ====

modules/ROOT/pages/docker/configuration.adoc

@@ -1,6 +1,6 @@
 [[docker-neo4j-configuration]]
-= Configuration
-:description: This chapter describes how configure Neo4j to run in a Docker container. 
+= Modify the default configuration 
+:description: This chapter describes how configure Neo4j to run in a Docker container.
 
 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 default memory assignments to Neo4j are very limited (`NEO4J_dbms_memory_pagecache_size=512M` and `NEO4J_dbms_memory_heap_max__size=512M`), to allow multiple containers to be run on the same server.

modules/ROOT/pages/docker/docker-compose-standalone.adoc

@@ -0,0 +1,108 @@
+:description: Running Neo4j in a Docker container using Docker Compose
+:page-role: enterprise-edition new-4.4.38
+
+[[docker-compose-neo4j-standalone]]
+= Deploy a Neo4j standalone server using Docker Compose
+
+You can deploy a Neo4j standalone server using Docker Compose by defining the container configuration in a _docker-compose.yml_ file and authenticating with basic authentication or Docker secrets.
+
+[[docker-compose-basic-authentication]]
+== Deploy a Neo4j server using basic authentication mechanism
+
+Before you start, verify that you have installed Docker Compose.
+For more information, see the https://docs.docker.com/compose/install/[Install Docker Compose official documentation].
+
+. Create a project folder where you will store your _docker-compose.yml_ file and run your Neo4j server.
+. Prepare your _docker-compose.yml_ file using the following example.
+For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification].
++
+.Example of a _docker-compose.yml_ file
+[source,yaml,subs="attributes+,+macros"]
+----
+services:
+  neo4j:
+    image: neo4j:latest
+    volumes:  # <1>
+        - /$HOME/neo4j/logs:/logs
+        - /$HOME/neo4j/config:/config
+        - /$HOME/neo4j/data:/data
+        - /$HOME/neo4j/plugins:/plugins
+    environment:
+        - NEO4J_AUTH=neo4j/your_password # <2>
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    restart: always
+----
+<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins.
+For more information about mounting volumes, see xref:docker/mounting-volumes.adoc[].
+<2> Set the `neo4j` username and password.
+
+. Deploy your Neo4j server by running `docker-compose up` from your project folder.
++
+[source,shell,subs="attributes+,+macros"]
+----
+docker-compose up -d
+----
++
+The `-d` flag starts the container in detached mode.
+
+[role=label--recommended]
+[[docker-compose-secrets]]
+== Deploy a Neo4j server with Docker secrets
+
+It is advisable not to store sensitive information, such as the database username and password, in the _docker-compose.yml_ file.
+You can instead store your credentials in files and use them in your _docker-compose.yml_ file without exposing their values.
+
+. Create a file, for example, _neo4j_auth.txt_, containing the username and password for the Neo4j server to be used as a Docker secret.
++
+[source,text,subs="attributes"]
+----
+neo4j/your_password
+----
+. Prepare your _docker-compose.yml_ file using the following example.
+For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification].
++
+.Example of a _docker-compose.yml_ file
+[source,yaml,subs="attributes+,+macros"]
+----
+services:
+  neo4j:
+    image: neo4j:latest
+    volumes: # <1>
+        - /$HOME/neo4j/logs:/logs
+        - /$HOME/neo4j/config:/config
+        - /$HOME/neo4j/data:/data
+        - /$HOME/neo4j/plugin:/plugins
+    environment:
+        - NEO4J_AUTH_FILE=/run/secrets/neo4j_auth_file # <2>
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    restart: always
+    secrets:
+      - neo4j_auth_file #<3>
+secrets:
+  neo4j_auth_file: # <4>
+    file: ./neo4j_auth.txt # <5>
+----
+<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins.
+<2> Path to the file where the value for the `NEO4J_AUTH` environment variable can be found.
+<3> The name of the secret, for example `neo4j_auth_file`.
+<4> Path to the _neo4j_auth.txt_ file.
+<5> The name of the secret in the `neo4j` service.
++
+[WARNING]
+====
+The secret value overrides the equivalent environment variable if they are both defined.
+So, for example, if you also define an environment variable `NEO4J_AUTH=neo4j/your_other_password` in the `environment` section of the `neo4j` service, the value of `NEO4J_AUTH_FILE` will be the one used.
+====
+
+. Deploy your Neo4j server by running `docker-compose up` from your project folder.
++
+[source,shell,subs="attributes+,+macros"]
+----
+docker-compose up -d
+----
++
+The `-d` flag starts the container in detached mode.

modules/ROOT/pages/docker/index.adoc

@@ -1,19 +1,24 @@
 [[docker]]
 = Docker
-:description: This chapter describes how run Neo4j in a Docker container. 
+:description: This chapter describes how run Neo4j in a Docker container.
 
 This chapter describes the following:
 
-* xref:docker/introduction.adoc[Introduction] -- Introduction to running Neo4j in a Docker container.
-* xref:docker/configuration.adoc[Configuration] -- How to configure Neo4j to run in a Docker container.
-* xref:docker/clustering.adoc[Clustering] -- How to set up Causal Clustering when using Docker.
-* xref:docker/operations.adoc[Docker specific operations] - Descriptions of various operations that are specific to using Docker.
+* xref:docker/introduction.adoc[Get started with Neo4j in Docker] -- Introduction to running Neo4j in a Docker container.
+* xref:docker/mounting-volumes.adoc[Persist data with Docker volumes] -- How and where to mount persistent storage to the Docker container.
+* xref:docker/configuration.adoc[Modify the default configuration] -- How to configure Neo4j to run in a Docker container.
+* xref:docker/plugins.adoc[Plugins] -- How to load plugins when using Neo4j in Docker.
+* xref:docker/docker-compose-standalone.adoc[Deploy a Neo4j server with Docker Compose] -- How to set up a Neo4j server with Docker Compose using a basic authentication mechanism or Docker secrets.
+* xref:docker/clustering.adoc[Deploy a Neo4j cluster on Docker] -- How to set up Causal Clustering when using Docker.
+* xref:docker/operations.adoc[Docker specific operations] -  Descriptions of various `neo4j-admin` and `cypher-shell` operations that are specific to using Docker.
 * xref:docker/security.adoc[Security] - Information about using encryption with the Docker image.
 * xref:docker/maintenance.adoc[Docker maintenance operations] How to maintain Neo4j when running in a Docker container.
 * xref:docker/ref-settings.adoc[Docker specific configuration settings] - A conversion table for the Neo4j configuration settings to Docker format.
 
+
 [NOTE]
+====
 Docker does not run natively on macOS or Windows.
 For running Docker on macOS and Windows, please consult the https://docs.docker.com/engine/installation[documentation provided by Docker].
-
+====
 

modules/ROOT/pages/docker/introduction.adoc

@@ -1,6 +1,6 @@
 :description: An introduction to how Neo4j runs in a Docker container.
 [[docker-overview]]
-= Introduction
+= Get started with Neo4j in Docker 
 
 Docker can be downloaded for macOS, Windows, and Linux operating systems from https://www.docker.com/get-started.
 DockerHub hosts an link:https://hub.docker.com/_/neo4j[official Neo4j image] that provides a standard, ready-to-run package of Neo4j Community Edition and Enterprise Edition for a variety of versions.
@@ -44,7 +44,7 @@ docker run \
     neo4j:{neo4j-version-exact}
 ----
 
-You can try out your Neo4j container by opening _http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser. 
+You can try out your Neo4j container by opening _http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser.
 By default, Neo4j requires authentication and prompts you to log in with a username/password of `neo4j/neo4j` at the first connection.
 You are then prompted to set a new password.
 
@@ -76,7 +76,7 @@ Please note that there is currently no way to change the initial username from `
 [[docker-volumes]]
 == Persisting data using Volumes
 
-The `--volume` option maps a local folder to the container, where you can persist data between restarts. 
+The `--volume` option maps a local folder to the container, where you can persist data between restarts.
 
 [source, shell, subs="attributes"]
 ----

modules/ROOT/pages/docker/mounting-volumes.adoc

@@ -0,0 +1,145 @@
+:description: How to use persistent storage when using Neo4j in Docker.
+[[docker-volumes]]
+= Persist data with Docker volumes
+
+Docker containers are ephemeral.
+When a container is stopped, any data written to it is lost.
+Therefore, if you want to persist data when using Neo4j in Docker, you must mount storage to the container.
+Storages also allow you to get data in and out of the container.
+
+Storage can be mounted to a container in two ways:
+
+* A folder on the host file system.
+* A Docker volume -- a named storage location that is managed by Docker.
+
+For instructions on _how_ to mount storage to a Docker container, refer to the official Docker documentation link:https://docs.docker.com/storage/bind-mounts/[Bind mounts^] and link:https://docs.docker.com/storage/volumes/[Volumes^].
+
+Neo4j provides several mount points for storage to simplify using Neo4j in Docker.
+The following sections describe the mount points and how to use them.
+
+[[docker-volumes-mount-points]]
+== Neo4j mount points and permissions
+
+The following table is a complete reference of the mount points recognized by the Neo4j Docker image, and file permissions.
+
+All the listed mount points are *optional*.
+Neo4j can run in Docker without any volumes mounted at all.
+However, mounting storage to `/data` is considered essential for all but the most basic use cases.
+
+[WARNING]
+====
+Running containerized Neo4j without a `/data` mount results in *unrecoverable data loss* if anything happens to the container.
+====
+
+.Mount points for the Neo4j container
+[options="header", cols="1m,1,4"]
+|===
+| Mount point
+| Permissions required
+| Description
+
+| /data
+| read, write
+| The data store for the Neo4j database. See xref:#docker-volumes-data[].
+
+| /logs
+| read, write
+| Output directory for Neo4j logs. See xref:#docker-volumes-logs[].
+
+| /conf
+| readfootnote:[Write permissions are required when using the xref:docker/configuration.adoc#docker-conf-volume[`dump-config`] feature.]
+| Pass configuration files to Neo4j on startup. +
+See xref:docker/configuration.adoc[].
+
+| /plugins
+| readfootnote:[Write permissions are required when using the xref:docker/plugins.adoc#docker-plugins-caching[`NEO4J_PLUGINS` feature] to download and store plugins.]
+| Allows you to install plugins in containerized Neo4j. +
+See xref:docker/plugins.adoc[].
+
+| /licenses
+| read
+| Provide licenses for Neo4j and any plugins by mounting the license folder. +
+See xref:docker/plugins.adoc#docker-plugins-licenses[Installing Plugin Licenses].
+
+| /import
+| read
+| Make _csv_ and other importable files available to xref:docker/operations.adoc#docker-neo4j-import[neo4j-admin import].
+
+| /ssl
+| read
+| Provide SSL certificates to Neo4j for message encryption. +
+See xref:docker/security.adoc[]
+
+| /metrics
+| write
+| label:enterprise[Enterprise Edition] Output directory for metrics files.
+See xref:monitoring/metrics/index.adoc[Metrics].
+|===
+
+[[docker-volumes-data]]
+=== Mounting storage to `/data`
+
+Neo4j inside Docker stores database files in the `/data` folder.
+By mounting storage to `/data`, any data written to Neo4j will persist after the container is stopped.
+
+Stopping the container and then restarting with the same folder mounted to `/data` starts a new containerized Neo4j instance with the same data.
+
+[CAUTION]
+====
+If Neo4j could not properly close down, it may have left data in a bad state and is likely to fail on startup.
+This is the same as if Neo4j is run outside a container and not closed properly.
+====
+
+.Two ways to mount storage to the `/data` mount point
+====
+.Mounting a folder to `/data`
+[source, shell, subs="attributes"]
+----
+docker run -it --rm \
+   --volume $HOME/neo4j/data:/data \
+   neo4j:{neo4j-version-exact}
+----
+
+.Creating a named volume and mounting it to `/data`
+[source, shell, subs="attributes+,+macros"]
+----
+docker volume create neo4jdata # <1>
+docker run -it --rm \
+   --volume neo4jdata:/data \  # <2>
+   neo4j:{neo4j-version-exact}
+----
+<1> Create a Docker volume named `neo4jdata`.
+<2> Mount the volume name `neo4jdata` to `/data`.
+====
+
+[[docker-volumes-logs]]
+=== Mounting storage to `/logs`
+
+Neo4j logging output is written to files in the _/logs_ directory.
+This directory is mounted as a _/logs_ volume.
+By mounting storage to `/logs`, the log files become available outside the container. +
+
+[TIP]
+====
+For more information about configuring Neo4j, see xref:docker/configuration.adoc[Configuration]. +
+For more information about the Neo4j log files, see xref:monitoring/logging.adoc[Logging].
+====
+
+
+[[docker-volumes-file-permissions]]
+== File permissions
+
+For security reasons, by default, Neo4j runs as the `neo4j` user inside the container.
+This user has user ID `7474`.
+If `neo4j` needs read or write access to a mounted folder, but does not have it, the folder will be automatically re-owned to `7474`.
+
+[NOTE]
+====
+This is a convenient feature, so you do not have to worry about the finer details of file permissions in Docker and can get started more easily.
+It does however mean that mounted folders change ownership, and you may find you can no longer read your files without root access.
+====
+
+=== Docker `run` with `--user` flag
+
+The `--user` flag to `docker run` forces Docker to run as the provided user.
+In this situation, if that user does not have the required read or write access to any mounted folders, Neo4j will fail to start.

modules/ROOT/pages/docker/operations.adoc

@@ -1,6 +1,6 @@
 [[docker-operations]]
 = Docker specific operations
-:description: How to use Neo4j tools when running Neo4j in a Docker container. 
+:description: How to use Neo4j tools when running Neo4j in a Docker container.
 
 [[docker-neo4j-admin]]
 == Use Neo4j Admin
@@ -165,7 +165,7 @@ match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.y
 .Invoke `cypher-shell` with the `--file` option
 [source, shell, subs="attributes"]
 ----
-# Put the example.cypher file in the local folder ./examples. 
+# Put the example.cypher file in the local folder ./examples.
 
 # Start a Neo4j container and mount the ./examples folder inside the container:
 
@@ -184,7 +184,7 @@ docker exec --interactive --tty <containerID/name> cypher-shell -u neo4j -p <pas
 .Use the `:source` command to run a Cypher script file
 [source, shell, subs="attributes"]
 ----
-# Put the example.cypher file in the local folder ./examples. 
+# Put the example.cypher file in the local folder ./examples.
 
 # Start a Neo4j container and mount the ./examples folder inside the container: