Installation and activation

Neo4j Desktop hosted Bloom client

Neo4j Bloom client comes pre-packaged within Neo4j Desktop. Starting with Bloom 1.3, the Bloom client is enabled and ready to use in Desktop. In Neo4j Desktop 1.2.5 and prior versions, the Bloom client app can be added to any project. Starting with Desktop 1.2.6, you can find and directly run the Bloom app from the “Applications” sidebar drawer. In case you are not seeing the Bloom app there, make sure offline mode is disabled and restart your Desktop. Your Desktop will automatically search for the latest version of Bloom and install it if it is either missing or an older version.

Prior to Bloom 1.3, an activation key was required before the Bloom app could be used in Desktop. Starting with Bloom 1.3, a licensing change was introduced to enable the Bloom client for personal development use in Desktop. The Bloom client’s visualization and exploration features are available with any locally installed databases in Desktop. Access to a remote Neo4j database and features used for collaboration, such as persistent storage and security, require the Bloom server component.

For more information on licensing terms, refer to the Neo4j Desktop license agreement from the “About” section of Neo4j Desktop.

Bloom server

The Bloom server component installs as a Neo4j database plugin. Before you can begin, download the Bloom server package here and make sure you have a valid activation key for the Bloom server. The server activation key can be obtained from your Neo4j representative.

Starting with Bloom 1.3, a licensed Bloom server component is required if you want to use the Bloom client (in Desktop or self-hosted) with a remotely hosted database on a Neo4j server or cluster.

Installing server plugin

Bloom supports both Neo4j 3.x and 4.x. Keep in mind that the different versions require different plugins. Also, the configuration is slightly different depending on the version of Neo4j used, as described below.

Installation Steps:
  1. Get the Bloom server plugin: Unzip the downloaded Bloom server package. The Bloom plugin (.jar file) to use depends on your Neo4j server version. Use the 3.x jar file for Neo4j 3.x and the 4.x jar file for Neo4j 4.x. For example, if you are using Neo4j 4.0.3 and Bloom 1.3.0, use bloom-plugin-4.x-1.3.0.jar.

  2. Place the plugin: First, take a look at the table in Operations Manual → File locations to find where to put the Bloom plugin .jar file. Make sure to copy the file to the correct plugins directory.

  3. Place the activation key: Place the activation key file provided on the Neo4j database server. You may place the file in any location of your choice. To avoid getting the file inadvertently overwritten, you may place it outside the Neo4j installation directory.

  4. Edit config file: Then, you will need to edit the neo4j.conf configuration file of the database. Read Operations Manual → The neo4j.conf file section in order to learn more about the neo4j.conf file. You can find the default location for your OS Operations Manual → File locations.

    You will need to add a configuration setting with the path to the Bloom license file:

    neo4j.bloom.license_file=<filepath>

    Bloom server accepts absolute, i.e. fully qualified starting with the OS base directory, as well as relative file paths, i.e. where the path is relative to the Neo4j database install directory. For example:

    neo4j.bloom.license_file=/etc/neo4j/license/mybloomkey.license
    neo4j.bloom.license_file=mybloomkey.license

    Add the unrestricted procedures setting to allow the Bloom server procedures to run.

    dbms.security.procedures.unrestricted=bloom.*

    If the setting already exists in neo4j.conf, do not add it again. Simply append to the existing value. Do the same for the procedure white list setting if you are using white listing.

    dbms.security.procedures.unrestricted=apoc.*,bloom.*
    dbms.security.procedures.allowlist=apoc.load.*,bloom.*

    In case the Bloom server plugin is also hosting the Bloom client, add the following configuration setting to the hosting Neo4j server or cluster member:

    For Neo4j 3.x:
    dbms.unmanaged_extension_classes=com.neo4j.bloom.server=/browser/bloom
    For Neo4j 4.0 and 4.1:
    dbms.unmanaged_extension_classes=com.neo4j.bloom.server=/bloom
    dbms.security.http_auth_whitelist=/,/browser.*,/bloom.*
    For Neo4j 4.2+:
    dbms.unmanaged_extension_classes=com.neo4j.bloom.server=/bloom
    dbms.security.http_auth_allowlist=/,/browser.*,/bloom.*
  5. Setup users/roles in the database: Add any users and roles to the Neo4j database as needed. By default, the Bloom server only authorizes users with the admin role to access Bloom. To enable users with other roles to have Bloom access using the server, add the roles to the neo4j.bloom.authorization_role property in neo4j.conf, as shown in Example 1 and 2 below.

    Example 1: To give access to users with the admin or architect role, the setting would be:

    neo4j.bloom.authorization_role=admin,architect

    Example 2: To give access to users with the admin, reader and a custom bloom role, the setting would be:

    neo4j.bloom.authorization_role=admin,reader,bloom
    When adding the plugin or changing the configuration file, you will need to restart the Neo4j database for the changes to be ready to use by the Bloom client.
  6. Share Perspectives with users: If needed, create and share Perspectives for any non-admin users who will be authorized for Bloom access. Best practice for assigning Perspectives is to create a custom role for each Perspective, and add that role to each user who should have access to the Perspective in question.

    Alternatively, if users will create their own Perspectives, grant them a role where they have access to create new data in the database. See Operations Manual → Authentication and Authorization for more info on roles in Neo4j.

    To learn more about sharing perspectives, please see Storage and sharing.

Updating server plugin

Updating the Bloom server plugin is easy. Simply remove the previous plugin from the appropriate plugins directory as mentioned above. Place the updated plugin provided in its place.

You will need to restart the Neo4j database for the new plugin to be loaded and ready to use by the Bloom client.

Accessing Neo4j server hosted Bloom

After configuring Neo4j and installing the plugin, Bloom will be available using HTTP or HTTPS as configured with one of these URLs.

For Neo4j 3.x:
http://<neo4j-server-host>:<http-port>/browser/bloom/

https://<neo4j-server-host>:<https-port>/browser/bloom/
For Neo4j 4.x:
http://<neo4j-server-host>:<http-port>/bloom/

https://<neo4j-server-host>:<https-port>/bloom/

Users will need to log in with their credentials as configured for the Neo4j database.

Bloom is supported on Chrome, Firefox and Edge web browsers. You may experience glitches or unexpected behaviour if using another web browser.