Skip to content

Commit b55df1e

Browse files
renetapopovarenetapopova
committed
add mounting volumes and plugins page
1 parent fb6c71f commit b55df1e

File tree

3 files changed

+317
-0
lines changed

3 files changed

+317
-0
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@
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[]
2527
** xref:docker/docker-compose-standalone.adoc[]
2628
** xref:docker/clustering.adoc[]
2729
** xref:docker/operations.adoc[]

‎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+
= Persisting 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/plugins.adoc‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
:description: How to load plugins when using Neo4j in Docker.
2+
[[docker-plugins]]
3+
= Plugins
4+
5+
6+
This page describes how to install plugins into a Neo4j instance running inside a Docker container.
7+
For instructions about plugins in general see xref:configuration/plugins.adoc[Configuration -> Plugins].
8+
9+
10+
11+
[[docker-plugins-procedures]]
12+
== Installing plugins
13+
14+
To install plugins, including link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/procedures#extending-neo4j-procedures[user-defined procedures], mount the folder or volume containing the plugin JARs to `/plugins`, for example:
15+
16+
[source, shell, subs="attributes"]
17+
----
18+
docker run \
19+
--publish=7474:7474 --publish=7687:7687 \
20+
--volume=$HOME/neo4j/plugins:/plugins \
21+
neo4j:{neo4j-version-exact}
22+
----
23+
24+
Neo4j automatically loads any plugins found in the `/plugins` folder on startup.
25+
26+
27+
[[docker-plugins-neo4jplugins]]
28+
== `NEO4J_PLUGINS` utility
29+
30+
The Neo4j Docker image includes a startup script that can automatically download and configure certain Neo4j plugins at runtime.
31+
32+
[NOTE]
33+
====
34+
This feature is intended to facilitate the use of the Neo4j plugins in development environments, but it is not recommended for production environments.
35+
36+
To use plugins in production with Neo4j Docker containers, see xref:docker/plugins.adoc#docker-plugins-procedures[Install user-defined procedures].
37+
====
38+
39+
The `NEO4J_PLUGINS` environment variable can be used to specify the plugins to install using this method.
40+
This should be set to a JSON-formatted list of the xref:configuration/plugins.adoc[supported plugins].
41+
42+
[NOTE]
43+
====
44+
Running Bloom in a Docker container requires Neo4j Docker image 4.2.3-enterprise or later.
45+
====
46+
47+
If invalid `NEO4J_PLUGINS` values are passed, Neo4j returns a notification that the plugin is not known.
48+
For example, `--env NEO4J_PLUGINS='["gds"]'` returns the following notification:
49+
50+
.Example output
51+
[source, shell, role="noheader"]
52+
----
53+
"gds" is not a known Neo4j plugin. Options are:
54+
apoc
55+
apoc-extended
56+
bloom
57+
graph-data-science
58+
graphql
59+
n10s
60+
----
61+
62+
.Install the APOC Core plugin (`apoc`)
63+
====
64+
You can use the Docker argument `--env NEO4J_PLUGINS='["apoc"]'` and run the following command:
65+
66+
[source, shell, subs="attributes"]
67+
----
68+
docker run -it --rm \
69+
--publish=7474:7474 --publish=7687:7687 \
70+
--env NEO4J_AUTH=none \
71+
--env NEO4J_PLUGINS='["apoc"]' \
72+
neo4j:{neo4j-version-exact}
73+
----
74+
====
75+
76+
.Install the APOC Core plugin (`apoc`) and the Graph Data Science plugin (`graph-data-science`)
77+
====
78+
You can use the Docker argument `--env NEO4J_PLUGINS='["apoc", "graph-data-science"]'` and run the following command:
79+
80+
[source, shell, subs="attributes"]
81+
----
82+
docker run -it --rm \
83+
--publish=7474:7474 --publish=7687:7687 \
84+
--env NEO4J_AUTH=none \
85+
--env NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
86+
neo4j:{neo4j-version-exact}
87+
----
88+
====
89+
90+
[[docker-plugins-caching]]
91+
== Storing downloaded plugins
92+
93+
In situations where bandwidth is limited, or Neo4j is stopped and started frequently, it may be desirable to download plugins once and re-use them rather than downloading them each time.
94+
95+
By using the `NEO4J_PLUGINS` utility in combination with mounting storage to `/plugins`, the plugin jars are downloaded into the `/plugins` folder.
96+
This can then be used again later to supply the same plugins to Neo4j without needing to set `NEO4J_PLUGINS`.
97+
98+
.Example of automatically downloading and re-using plugins with docker.
99+
====
100+
.Get the APOC plugin and save it into `$HOME/neo4j/plugins`
101+
[source, shell, subs="attributes+,+macros"]
102+
----
103+
docker run -it --rm \
104+
--publish=7474:7474 --publish=7687:7687 \
105+
--env NEO4J_AUTH=none \
106+
--env NEO4J_PLUGINS='["apoc"]' \
107+
--volume=$HOME/neo4j/plugins:/plugins \ # <1>
108+
neo4j:{neo4j-version-exact}
109+
----
110+
<1> Mounts host folder `$HOME/neo4j/plugins` to `/plugins`.
111+
112+
.Verify the `apoc` plugin is downloaded.
113+
[source, shell]
114+
----
115+
docker kill <containerID/name>
116+
ls $HOME/neo4j/plugins
117+
apoc.jar
118+
----
119+
120+
.Start a new container and verify `apoc` is installed.
121+
[source, shell, subs="attributes"]
122+
----
123+
docker run -it --rm \
124+
--publish=7474:7474 --publish=7687:7687 \
125+
--env NEO4J_AUTH=none \
126+
--volume=$HOME/neo4j/plugins:/plugins \
127+
neo4j:{neo4j-version-exact}
128+
129+
cypher-shell "RETURN apoc.version();"
130+
----
131+
====
132+
133+
[[docker-plugins-licenses]]
134+
== Installing plugin licenses
135+
136+
If a plugin requires a license, the license file can be supplied to the container by mounting the folder or volume containing license file(s) to `/licenses`.
137+
138+
[NOTE]
139+
====
140+
To check if the plugin requires a license, refer to the xref:configuration/plugins.adoc[general plugin documentation].
141+
====
142+
143+
.Installing plugins and licenses by mounting folders to the container
144+
====
145+
[source, shell, subs="attributes+,+macros"]
146+
----
147+
docker run \
148+
--publish=7474:7474 --publish=7687:7687 \
149+
--volume=$HOME/neo4j/plugins:/plugins \ # <1>
150+
--volume=$HOME/neo4j/licenses:/licenses \ # <2>
151+
neo4j:{neo4j-version-exact}
152+
----
153+
<1> folder containing plugin jars.
154+
<2> folder containing license files.
155+
====
156+
157+
The licenses must also be provided if using the `NEO4J_PLUGINS` utility to install the plugins.
158+
159+
.Installing plugins and licenses by mounting folders to the container using `NEO4J_PLUGINS` utility
160+
====
161+
[source, shell, subs="attributes+,+macros"]
162+
----
163+
docker run \
164+
--publish=7474:7474 --publish=7687:7687 \
165+
--env NEO4J_PLUGINS='["bloom"]' \
166+
--volume=$HOME/neo4j/licenses:/licenses \ # <1>
167+
neo4j:{neo4j-version-exact}
168+
----
169+
<1> A folder containing license files.
170+
====

0 commit comments

Comments
 (0)