From 88649dfbd226d1fdf9ad0f34b68106a0f3839236 Mon Sep 17 00:00:00 2001 From: Giuseppe Villani Date: Fri, 21 Jul 2023 17:26:45 +0200 Subject: [PATCH] Update installation docs with docker and desktop, created partial and small fixes (#3672) --- .../ROOT/pages/installation/index.adoc | 33 ++------- .../modules/ROOT/partials/docker.adoc | 32 +++++++-- .../modules/ROOT/partials/neo4j-desktop.adoc | 11 +++ .../modules/ROOT/partials/neo4j-server.adoc | 36 +++++++++- readme.adoc | 71 ++----------------- 5 files changed, 84 insertions(+), 99 deletions(-) create mode 100644 docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc diff --git a/docs/asciidoc/modules/ROOT/pages/installation/index.adoc b/docs/asciidoc/modules/ROOT/pages/installation/index.adoc index 7419ae600e..2271db9ca0 100644 --- 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: `.` version. -The trailing `` 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 () 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 index 50de3aa6a8..3e2ad0b46b 100644 --- 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[] \ No newline at end of file diff --git a/docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc b/docs/asciidoc/modules/ROOT/partials/neo4j-desktop.adoc new file mode 100644 index 0000000000..c7291016ee --- /dev/null +++ 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 index 2c075ee819..73b172da53 100644 --- 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: `.` version. +The trailing `` 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: `.` version. +The trailing `` 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[] \ No newline at end of file diff --git a/readme.adoc b/readme.adoc index 2eb200f703..909a26becb 100644 --- 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: `.` version. -The trailing `` 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