Skip to content

Commit b6021a1

Browse files
renetapopovastefgia
renetapopova
and
stefgia
authored
Add missing content to the Docker docs (#1804) (#1916)
https://trello.com/c/MgmtbjRJ/1470-support-docker-secrets * Adds documentation for general docker compose usage * Adds documentation for using secrets with neo4j --------- Cherry-picked from #1804 * Add documentation for persistent volumes as in 5.x * Add documentation for plugins as in 5.x --------- Co-authored-by: Stefanos Giagkiozis <[email protected]>
1 parent 53c556d commit b6021a1

File tree

9 files changed

+447
-16
lines changed

9 files changed

+447
-16
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@
2121
2222
* xref:docker/index.adoc[]
2323
** xref:docker/introduction.adoc[]
24+
** xref:docker/mounting-volumes.adoc[]
2425
** xref:docker/configuration.adoc[]
26+
** xref:docker/plugins.adoc[]
27+
** xref:docker/docker-compose-standalone.adoc[]
2528
** xref:docker/clustering.adoc[]
2629
** xref:docker/operations.adoc[]
2730
** xref:docker/security.adoc[]

‎modules/ROOT/pages/docker/clustering.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[role=enterprise-edition]
22
[[docker-cc]]
3-
= Clustering
4-
:description: How to deploy a Causal Cluster setup in a containerized environment without an orchestration tool.
3+
= Deploy a Neo4j cluster on Docker
4+
:description: How to deploy a Causal Cluster setup in a containerized environment without an orchestration tool.
55

66
[NOTE]
77
====

‎modules/ROOT/pages/docker/configuration.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[docker-neo4j-configuration]]
2-
= Configuration
3-
:description: This chapter describes how configure Neo4j to run in a Docker container.
2+
= Modify the default configuration 
3+
:description: This chapter describes how configure Neo4j to run in a Docker container.
44

55
The default configuration provided by this image is intended for learning about Neo4j, but must be modified to make it suitable for production use.
66
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‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
:description: Running Neo4j in a Docker container using Docker Compose
2+
:page-role: new-4.4.38
3+
4+
[[docker-compose-neo4j-standalone]]
5+
= Deploy a Neo4j standalone server using Docker Compose
6+
7+
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.
8+
9+
[[docker-compose-basic-authentication]]
10+
== Deploy a Neo4j server using basic authentication mechanism
11+
12+
Before you start, verify that you have installed Docker Compose.
13+
For more information, see the https://docs.docker.com/compose/install/[Install Docker Compose official documentation].
14+
15+
. Create a project folder where you will store your _docker-compose.yml_ file and run your Neo4j server.
16+
. Prepare your _docker-compose.yml_ file using the following example.
17+
For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification].
18+
+
19+
.Example of a _docker-compose.yml_ file
20+
[source,yaml,subs="attributes+,+macros"]
21+
----
22+
services:
23+
neo4j:
24+
image: neo4j:{neo4j-version-exact}
25+
volumes: # <1>
26+
- /$HOME/neo4j/logs:/logs
27+
- /$HOME/neo4j/config:/config
28+
- /$HOME/neo4j/data:/data
29+
- /$HOME/neo4j/plugins:/plugins
30+
environment:
31+
- NEO4J_AUTH=neo4j/your_password # <2>
32+
ports:
33+
- "7474:7474"
34+
- "7687:7687"
35+
restart: always
36+
----
37+
<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins.
38+
For more information about mounting volumes, see xref:docker/mounting-volumes.adoc[].
39+
<2> Set the `neo4j` username and password.
40+
41+
. Deploy your Neo4j server by running `docker-compose up` from your project folder.
42+
+
43+
[source,shell,subs="attributes+,+macros"]
44+
----
45+
docker-compose up -d
46+
----
47+
+
48+
The `-d` flag starts the container in detached mode.
49+
50+
[role=label--recommended]
51+
[[docker-compose-secrets]]
52+
== Deploy a Neo4j server with Docker secrets
53+
54+
It is advisable not to store sensitive information, such as the database username and password, in the _docker-compose.yml_ file.
55+
You can instead store your credentials in files and use them in your _docker-compose.yml_ file without exposing their values.
56+
57+
. Create a file, for example, _neo4j_auth.txt_, containing the username and password for the Neo4j server to be used as a Docker secret.
58+
+
59+
[source,text,subs="attributes"]
60+
----
61+
neo4j/your_password
62+
----
63+
. Prepare your _docker-compose.yml_ file using the following example.
64+
For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification].
65+
+
66+
.Example of a _docker-compose.yml_ file
67+
[source,yaml,subs="attributes+,+macros"]
68+
----
69+
services:
70+
neo4j:
71+
image: neo4j:{neo4j-version-exact}
72+
volumes: # <1>
73+
- /$HOME/neo4j/logs:/logs
74+
- /$HOME/neo4j/config:/config
75+
- /$HOME/neo4j/data:/data
76+
- /$HOME/neo4j/plugin:/plugins
77+
environment:
78+
- NEO4J_AUTH_FILE=/run/secrets/neo4j_auth_file # <2>
79+
ports:
80+
- "7474:7474"
81+
- "7687:7687"
82+
restart: always
83+
secrets:
84+
- neo4j_auth_file #<3>
85+
secrets:
86+
neo4j_auth_file: # <4>
87+
file: ./neo4j_auth.txt # <5>
88+
----
89+
<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins.
90+
<2> Path to the file where the value for the `NEO4J_AUTH` environment variable can be found.
91+
<3> The name of the secret, for example `neo4j_auth_file`.
92+
<4> Path to the _neo4j_auth.txt_ file.
93+
<5> The name of the secret in the `neo4j` service.
94+
+
95+
[WARNING]
96+
====
97+
The secret value overrides the equivalent environment variable if they are both defined.
98+
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.
99+
====
100+
101+
. Deploy your Neo4j server by running `docker-compose up` from your project folder.
102+
+
103+
[source,shell,subs="attributes+,+macros"]
104+
----
105+
docker-compose up -d
106+
----
107+
+
108+
The `-d` flag starts the container in detached mode.

‎modules/ROOT/pages/docker/index.adoc‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,24 @@
11
[[docker]]
22
= Docker
3-
:description: This chapter describes how run Neo4j in a Docker container.
3+
:description: This chapter describes how run Neo4j in a Docker container.
44

55
This chapter describes the following:
66

7-
* xref:docker/introduction.adoc[Introduction] -- Introduction to running Neo4j in a Docker container.
8-
* xref:docker/configuration.adoc[Configuration] -- How to configure Neo4j to run in a Docker container.
9-
* xref:docker/clustering.adoc[Clustering] -- How to set up Causal Clustering when using Docker.
10-
* xref:docker/operations.adoc[Docker specific operations] - Descriptions of various operations that are specific to using Docker.
7+
* xref:docker/introduction.adoc[Get started with Neo4j in Docker] -- Introduction to running Neo4j in a Docker container.
8+
* xref:docker/mounting-volumes.adoc[Persist data with Docker volumes] -- How and where to mount persistent storage to the Docker container.
9+
* xref:docker/configuration.adoc[Modify the default configuration] -- How to configure Neo4j to run in a Docker container.
10+
* xref:docker/plugins.adoc[Plugins] -- How to load plugins when using Neo4j in Docker.
11+
* 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.
12+
* xref:docker/clustering.adoc[Deploy a Neo4j cluster on Docker] -- How to set up Causal Clustering when using Docker.
13+
* xref:docker/operations.adoc[Docker specific operations] -  Descriptions of various `neo4j-admin` and `cypher-shell` operations that are specific to using Docker.
1114
* xref:docker/security.adoc[Security] - Information about using encryption with the Docker image.
1215
* xref:docker/maintenance.adoc[Docker maintenance operations] How to maintain Neo4j when running in a Docker container.
1316
* xref:docker/ref-settings.adoc[Docker specific configuration settings] - A conversion table for the Neo4j configuration settings to Docker format.
1417

18+
1519
[NOTE]
20+
====
1621
Docker does not run natively on macOS or Windows.
1722
For running Docker on macOS and Windows, please consult the https://docs.docker.com/engine/installation[documentation provided by Docker].
18-
23+
====
1924

‎modules/ROOT/pages/docker/introduction.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:description: An introduction to how Neo4j runs in a Docker container.
22
[[docker-overview]]
3-
= Introduction
3+
= Get started with Neo4j in Docker 
44

55
Docker can be downloaded for macOS, Windows, and Linux operating systems from https://www.docker.com/get-started.
66
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 \
4444
neo4j:{neo4j-version-exact}
4545
----
4646

47-
You can try out your Neo4j container by opening _http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser.
47+
You can try out your Neo4j container by opening _http://localhost:7474/_ (the Neo4j's Browser interface) in a web browser.
4848
By default, Neo4j requires authentication and prompts you to log in with a username/password of `neo4j/neo4j` at the first connection.
4949
You are then prompted to set a new password.
5050

@@ -76,7 +76,7 @@ Please note that there is currently no way to change the initial username from `
7676
[[docker-volumes]]
7777
== Persisting data using Volumes
7878

79-
The `--volume` option maps a local folder to the container, where you can persist data between restarts.
79+
The `--volume` option maps a local folder to the container, where you can persist data between restarts.
8080

8181
[source, shell, subs="attributes"]
8282
----

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

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
:description: How to use persistent storage when using Neo4j in Docker.
2+
[[docker-volumes]]
3+
= Persist data with Docker volumes
4+
5+
Docker containers are ephemeral.
6+
When a container is stopped, any data written to it is lost.
7+
Therefore, if you want to persist data when using Neo4j in Docker, you must mount storage to the container.
8+
Storages also allow you to get data in and out of the container.
9+
10+
Storage can be mounted to a container in two ways:
11+
12+
* A folder on the host file system.
13+
* A Docker volume -- a named storage location that is managed by Docker.
14+
15+
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^].
16+
17+
Neo4j provides several mount points for storage to simplify using Neo4j in Docker.
18+
The following sections describe the mount points and how to use them.
19+
20+
[[docker-volumes-mount-points]]
21+
== Neo4j mount points and permissions
22+
23+
The following table is a complete reference of the mount points recognized by the Neo4j Docker image, and file permissions.
24+
25+
All the listed mount points are *optional*.
26+
Neo4j can run in Docker without any volumes mounted at all.
27+
However, mounting storage to `/data` is considered essential for all but the most basic use cases.
28+
29+
[WARNING]
30+
====
31+
Running containerized Neo4j without a `/data` mount results in *unrecoverable data loss* if anything happens to the container.
32+
====
33+
34+
.Mount points for the Neo4j container
35+
[options="header", cols="1m,1,4"]
36+
|===
37+
| Mount point
38+
| Permissions required
39+
| Description
40+
41+
| /data
42+
| read, write
43+
| The data store for the Neo4j database. See xref:#docker-volumes-data[].
44+
45+
| /logs
46+
| read, write
47+
| Output directory for Neo4j logs. See xref:#docker-volumes-logs[].
48+
49+
| /conf
50+
| readfootnote:[Write permissions are required when using the xref:docker/configuration.adoc#docker-conf-volume[`dump-config`] feature.]
51+
| Pass configuration files to Neo4j on startup. +
52+
See xref:docker/configuration.adoc[].
53+
54+
| /plugins
55+
| readfootnote:[Write permissions are required when using the xref:docker/plugins.adoc#docker-plugins-caching[`NEO4J_PLUGINS` feature] to download and store plugins.]
56+
| Allows you to install plugins in containerized Neo4j. +
57+
See xref:docker/plugins.adoc[].
58+
59+
| /licenses
60+
| read
61+
| Provide licenses for Neo4j and any plugins by mounting the license folder. +
62+
See xref:docker/plugins.adoc#docker-plugins-licenses[Installing Plugin Licenses].
63+
64+
| /import
65+
| read
66+
| Make _csv_ and other importable files available to xref:docker/operations.adoc#docker-neo4j-import[neo4j-admin import].
67+
68+
| /ssl
69+
| read
70+
| Provide SSL certificates to Neo4j for message encryption. +
71+
See xref:docker/security.adoc[]
72+
73+
| /metrics
74+
| write
75+
| label:enterprise[Enterprise Edition] Output directory for metrics files.
76+
See xref:monitoring/metrics/index.adoc[Metrics].
77+
|===
78+
79+
[[docker-volumes-data]]
80+
=== Mounting storage to `/data`
81+
82+
Neo4j inside Docker stores database files in the `/data` folder.
83+
By mounting storage to `/data`, any data written to Neo4j will persist after the container is stopped.
84+
85+
Stopping the container and then restarting with the same folder mounted to `/data` starts a new containerized Neo4j instance with the same data.
86+
87+
[CAUTION]
88+
====
89+
If Neo4j could not properly close down, it may have left data in a bad state and is likely to fail on startup.
90+
This is the same as if Neo4j is run outside a container and not closed properly.
91+
====
92+
93+
.Two ways to mount storage to the `/data` mount point
94+
====
95+
.Mounting a folder to `/data`
96+
[source, shell, subs="attributes"]
97+
----
98+
docker run -it --rm \
99+
--volume $HOME/neo4j/data:/data \
100+
neo4j:{neo4j-version-exact}
101+
----
102+
103+
.Creating a named volume and mounting it to `/data`
104+
[source, shell, subs="attributes+,+macros"]
105+
----
106+
docker volume create neo4jdata # <1>
107+
docker run -it --rm \
108+
--volume neo4jdata:/data \ # <2>
109+
neo4j:{neo4j-version-exact}
110+
----
111+
<1> Create a Docker volume named `neo4jdata`.
112+
<2> Mount the volume name `neo4jdata` to `/data`.
113+
====
114+
115+
[[docker-volumes-logs]]
116+
=== Mounting storage to `/logs`
117+
118+
Neo4j logging output is written to files in the _/logs_ directory.
119+
This directory is mounted as a _/logs_ volume.
120+
By mounting storage to `/logs`, the log files become available outside the container. +
121+
122+
[TIP]
123+
====
124+
For more information about configuring Neo4j, see xref:docker/configuration.adoc[Configuration]. +
125+
For more information about the Neo4j log files, see xref:monitoring/logging.adoc[Logging].
126+
====
127+
128+
129+
[[docker-volumes-file-permissions]]
130+
== File permissions
131+
132+
For security reasons, by default, Neo4j runs as the `neo4j` user inside the container.
133+
This user has user ID `7474`.
134+
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`.
135+
136+
[NOTE]
137+
====
138+
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.
139+
It does however mean that mounted folders change ownership, and you may find you can no longer read your files without root access.
140+
====
141+
142+
=== Docker `run` with `--user` flag
143+
144+
The `--user` flag to `docker run` forces Docker to run as the provided user.
145+
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‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[[docker-operations]]
22
= Docker specific operations
3-
:description: How to use Neo4j tools when running Neo4j in a Docker container.
3+
:description: How to use Neo4j tools when running Neo4j in a Docker container.
44

55
[[docker-neo4j-admin]]
66
== Use Neo4j Admin
@@ -165,7 +165,7 @@ match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.y
165165
.Invoke `cypher-shell` with the `--file` option
166166
[source, shell, subs="attributes"]
167167
----
168-
# Put the example.cypher file in the local folder ./examples.
168+
# Put the example.cypher file in the local folder ./examples.
169169
170170
# Start a Neo4j container and mount the ./examples folder inside the container:
171171
@@ -184,7 +184,7 @@ docker exec --interactive --tty <containerID/name> cypher-shell -u neo4j -p <pas
184184
.Use the `:source` command to run a Cypher script file
185185
[source, shell, subs="attributes"]
186186
----
187-
# Put the example.cypher file in the local folder ./examples.
187+
# Put the example.cypher file in the local folder ./examples.
188188
189189
# Start a Neo4j container and mount the ./examples folder inside the container:
190190

0 commit comments

Comments
 (0)