Update installation docs with docker and desktop, created partial and…

… small fixes (#3672)
neo4j-contrib · Jul 21, 2023 · 88649df · 88649df
1 parent a75e38c
commit 88649df
Show file tree

Hide file tree

Showing 5 changed files with 84 additions and 99 deletions.
diff --git a/docs/asciidoc/modules/ROOT/pages/installation/index.adoc b/docs/asciidoc/modules/ROOT/pages/installation/index.adoc
@@ -9,40 +9,17 @@ _APOC Extended_ can be downloaded using one of the methods described in the sect
 
 include::partial$neo4j-server.adoc[tags=install,leveloffset=2]
 
-After you move the jar file to the plugins folder you have to restart neo4j with `neo4j restart`
-
-// tag::version-matrix[]
-Since APOC relies on Neo4j's internal APIs, you need to use the right APOC version for your Neo4j installation.
-
-APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version.
-The trailing `<apoc>` part of the version number will be incremented with every apoc release.
-
-The version compatibility matrix explains the mapping between Neo4j and APOC versions:
-
-[opts=header]
-|===
-|apoc version | neo4j version
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.10.0[5.10.0^] | 5.10.0 (5.10.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.9.0[5.9.0^] | 5.9.0 (5.9.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.8.0[5.8.0^] | 5.8.0 (5.8.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.7.0[5.7.0^] | 5.7.0 (5.7.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.6.0[5.6.0^] | 5.6.0 (5.6.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.5.0[5.5.0^] | 5.5.0 (5.5.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.4.0[5.4.0^] | 5.4.0 (5.4.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.3.1[5.3.1^] | 5.3.0 (5.3.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.2.0[5.2.0^] | 5.2.0 (5.2.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.1.0[5.1.0^] | 5.1.0 (5.1.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.4.0.19[4.4.0.19^] | 4.4.0 (4.4.x)
-|===
-
-// end::version-matrix[]
-
 If by mistake a jar not compatible with the neo4j version is inserted, a `log.warn` like this will appear in `neo4j.log`:
 ```
 The apoc version (<APOC_VERSION>) and the Neo4j DBMS versions [NEO4J_VERSION] are incompatible. 
 See the compatibility matrix in https://neo4j.com/labs/apoc/4.4/installation/ to see the correct version
 ```
 
+[[neo4j-desktop]]
+== Neo4j Desktop
+
+include::partial$neo4j-desktop.adoc[tags=install-desktop,leveloffset=2]
+
 [[docker]]
 == Docker
 

diff --git a/docs/asciidoc/modules/ROOT/partials/docker.adoc b/docs/asciidoc/modules/ROOT/partials/docker.adoc
@@ -2,16 +2,40 @@
 
 // tag::docker[]
 
-APOC Extended can be used with Docker.
+APOC Extended can be used with the https://hub.docker.com/_/neo4j/[Neo4j Docker image] via the `NEO4J_PLUGINS=apoc-extended` environment variable.
+
+If we use this environment variable, the APOC plugin will be downloaded and configured at runtime.
 
 [NOTE]
 ====
 This feature is intended to facilitate using APOC in development environments, but it is not recommended for use in production environments.
 ====
 
-Download the APOC release matching our Neo4j version and, copy it to a local folder, and supply it as a data volume mounted at `/plugins`.
+.The following runs Neo4j {neo4j-version} in a Docker container with the latest version of the APOC Library
+[source,bash,subs=attributes]
+----
+docker run \
+    -p 7474:7474 -p 7687:7687 \
+    -v $PWD/data:/data -v $PWD/plugins:/plugins \
+    --name neo4j-apoc \
+    -e NEO4J_apoc_export_file_enabled=true \
+    -e NEO4J_apoc_import_file_enabled=true \
+    -e NEO4J_apoc_import_file_use__neo4j__config=true \
+    -e NEO4J_PLUGINS=\[\"apoc-extended\"\] \
+    neo4j:{neo4j-version}
+----
+
+We should see the following two lines in the output after running this command:
+
+[source,text,subs=attributes]
+----
+Fetching versions.json for Plugin 'apoc' from https://neo4j-contrib.github.io/neo4j-apoc-procedures/versions.json
+Installing Plugin 'apoc' from https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/{apoc-release}-extended.jar to /plugins/apoc.jar
+----
+
+In a production environment we should download the https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/apoc-{apoc-release}-extended.jar[APOC release] matching our Neo4j version and, copy it to a local folder, and supply it as a data volume mounted at `/plugins`.
 
-.The following downloads the APOC Extended library into the `plugins` directory and then mounts that folder to the Neo4j Docker container
+.The following downloads the APOC Extended Library into the `plugins` directory and then mounts that folder to the Neo4j Docker container
 [source,bash,subs=attributes]
 ----
 mkdir plugins
@@ -35,4 +59,4 @@ docker run \
     neo4j
 ----
 
-// end::docker[]
+// end::docker[]
diff --git a/docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc b/docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc
@@ -0,0 +1,11 @@
+// tag::install-desktop[]
+
+APOC Extended cannot be installed via the `Plugins` tab.
+The present "APOC" box installs APOC core instead, that is:
+
+image::{img}/desktop-apoc.jpg[width=500]
+
+In order to install APOC Extended, we necessarily have to download the compatible version https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases[from here],
+and the put it manually into the `$NEO4J_HOME/plugins` folder.
+
+// end::install-desktop[]
diff --git a/docs/asciidoc/modules/ROOT/partials/neo4j-server.adoc b/docs/asciidoc/modules/ROOT/partials/neo4j-server.adoc
@@ -1,10 +1,42 @@
-== Manual Installation: Download latest release
+
 
 // tag::install[]
 
 Since APOC relies on Neo4j's internal APIs you need to use the *matching APOC version* for your Neo4j installation.
+
+APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version.
+The trailing `<apoc>` part of the version number will be incremented with every apoc release.
+
 Make sure that the *first two version numbers match between Neo4j and APOC*.
 
-Go to https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases[here] for all the APOC extended releases and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.
+Go https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases[here] for all the APOC extended releases and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.
+
+After you move the jar file to the plugins folder you have to restart neo4j with `neo4j restart`
+
+// tag::version-matrix[]
+=== Version Compatibility Matrix
+
+APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version.
+The trailing `<apoc>` part of the version number will be incremented with every apoc release.
+
+The version compatibility matrix explains the mapping between Neo4j and APOC versions:
+
+[opts=header]
+|===
+|apoc version | neo4j version
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.10.0[5.10.0^] | 5.10.0 (5.10.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.9.0[5.9.0^] | 5.9.0 (5.9.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.8.0[5.8.0^] | 5.8.0 (5.8.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.7.0[5.7.0^] | 5.7.0 (5.7.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.6.0[5.6.0^] | 5.6.0 (5.6.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.5.0[5.5.0^] | 5.5.0 (5.5.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.4.0[5.4.0^] | 5.4.0 (5.4.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.3.1[5.3.1^] | 5.3.0 (5.3.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.2.0[5.2.0^] | 5.2.0 (5.2.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.1.0[5.1.0^] | 5.1.0 (5.1.x)
+| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.4.0.18[4.4.0.18^] | 4.4.0 (4.4.x)
+|===
+
+// end::version-matrix[]
 
 // end::install[]
diff --git a/readme.adoc b/readme.adoc
@@ -46,6 +46,10 @@ https://matrix.wikia.com/wiki/Apoc[Apoc^] was the technician and driver on board
 // end::name-history-text[]
 // end::name-history[]
 
+== Installation: with Neo4j Desktop
+
+include::docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc[tags=install-desktop,leveloffset=2]
+
 == Feedback
 
 // tag::feedback[]
@@ -143,20 +147,11 @@ h| Output Return Columns |
 
 == Manual Installation: Download the latest release
 
-// tag::install[]
-
-Since APOC relies on Neo4j's internal APIs you need to use the *matching APOC version* for your Neo4j installation.
-Make sure that the *first two version numbers match between Neo4j and APOC*.
+include::docs/asciidoc/modules/ROOT/partials/neo4j-server.adoc[tags=install,leveloffset=1]
 
-Go to https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases[here] for all the APOC extended releases and download the binary jar to place into your `$NEO4J_HOME/plugins` folder.
-
-
-// end::install[]
 
 == Manual Configuration
 
-
-
 [WARNING]
 ====
 // tag::warnings[]
@@ -169,63 +164,9 @@ For more details, see {docs}/installation#restricted[the APOC installation docum
 
 
 
-// tag::version-matrix[]
-=== Version Compatibility Matrix
-
-Since APOC relies in some places on Neo4j's internal APIs you need to use the right APOC version for your Neo4j installaton.
-
-APOC uses a consistent versioning scheme: `<neo4j-version>.<apoc>` version. 
-The trailing `<apoc>` part of the version number will be incremented with every apoc release.
-
-[opts=header]
-|===
-|apoc version | neo4j version
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.10.0[5.10.0^] | 5.10.0 (5.10.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.9.0[5.9.0^] | 5.9.0 (5.9.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.8.0[5.8.0^] | 5.8.0 (5.8.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.7.0[5.7.0^] | 5.7.0 (5.7.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.6.0[5.6.0^] | 5.6.0 (5.6.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.5.0[5.5.0^] | 5.5.0 (5.5.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.4.0[5.4.0^] | 5.4.0 (5.4.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.3.1[5.3.1^] | 5.3.0 (5.3.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.2.0[5.2.0^] | 5.2.0 (5.2.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/5.1.0[5.1.0^] | 5.1.0 (5.1.x)
-| https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/4.4.0.19[4.4.0.19^] | 4.4.0 (4.4.x)
-|===
-
-// end::version-matrix[]
 === Using APOC with the Neo4j Docker image
 
-// tag::docker[]
-
-To use APOC with Docker; download the APOC release matching your Neo4j version and copy it to a local folder, supplying it as a data volume mounted at `/plugins`.
-
-.The following downloads the APOC Library into the `plugins` directory and then mounts that folder to the Neo4j Docker container
-[source,bash,subs=attributes]
-----
-mkdir plugins
-pushd plugins
-wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/{apoc-release}/apoc-{apoc-release}-extended.jar
-popd
-docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:{branch}
-----
-
-If you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:
-
-[source,bash]
-----
-docker run \
-    -p 7474:7474 -p 7687:7687 \
-    -v $PWD/data:/data -v $PWD/plugins:/plugins \
-    --name neo4j-apoc \
-    -e NEO4J_apoc_export_file_enabled=true \
-    -e NEO4J_apoc_import_file_enabled=true \
-    -e NEO4J_apoc_import_file_use__neo4j__config=true \
-    neo4j
-----
-
-// end::docker[]
-// tag::build[]
+include::docs/asciidoc/modules/ROOT/partials/docker.adoc[tags=docker,leveloffset=1]
 
 === Build & install the current development branch from source