Installation

This chapter describes how to install Neo4j Bloom and its different deployment modes.

Pre-requisites and system requirements

Bloom client

  • User access to a Neo4j Enterprise Edition database.

  • GPU-enabled client machine or VM, discrete GPU is preferred.

Note that a GPU passthrough setup, with a discrete GPU assigned to each VM, can be used in case the VM on the client side doesn’t have a GPU.
Neo4j Desktop hosted

  • Neo4j Desktop 1.2.5 and above.

Web server hosted

  • Chrome, Firefox or Edge web browser.

For faster search performance, it is highly recommended to set up indexes in the Neo4j database for all properties that should be searchable in Bloom. In general, full-text search indexes are recommended and are required if you want case-insensitive text matching.

Compatibility mode

Note that sometimes, due to compatibility issues between GPU and WebGL, the visualization may not appear at all. This issue is most common on Intel embedded GPUs running under a Linux operating system, but it may also be found in other configurations. Enabling Graph layout compatibility mode (found in Settings of the Bloom client) can help solve this issue and make the visualization appear. However, some of the application functionality may not work as expected. We recommend using a Windows or Mac client environment with discrete GPUs.

compatibility mode

Bloom server

  • Admin access to a licensed Neo4j Enterprise Edition database.

  • Neo4j Bloom server activation key.

To obtain activation keys for the Bloom client or server components, ask your friendly neighborhood Neo4j representative.

Version Compatibility

  • Neo4j Enterprise Edition database versions supported: 4.3.0+, 4.2.0+, 4.1.0+, 4.0.2+, 3.5.x.

  • Chrome, Firefox, and Edge (based on Chromium) browsers: Latest version recommended.

  • Neo4j database versions 4.0.0 and 4.0.1 are not supported.

  • The Fabric capability of Neo4j 4.x is currently not supported.

Keep in mind that if the Bloom client is used with the server component, both client and server should be the same exact version.

 

Bloom deployment modes

The Bloom client app in Neo4j Desktop can be used independent of the Bloom server component. The client makes a direct connection to your Neo4j graph database and runs queries directly using this connection.

But, Bloom is significantly more useful when both the client and server components are used together. In a multi-user, team, or multi-team environment, where collaboration between users is essential, user access control is needed, and persistent, reliable storage is non-negotiable, you will need to use the two components together. Further, as explained in Neo4j Desktop hosted Bloom client, the Bloom server component is now required when the client connects to a remotely hosted Neo4j database.

There are several deployment modes possible for Bloom.

Bloom app in Neo4j Desktop

Without the Bloom server

In this mode, the standalone Bloom app can connect to a Neo4j database locally created in Desktop only. Without the Bloom server, the client will store Perspective definition in a local storage allocated to the app. This is effectively a single user mode for Bloom and may be used in an evaluation or proof of concept to try Bloom against your graph data.

Since local storage is not considered persistent over the long term, consider exporting Perspectives if you wish to preserve them and to avoid accidental deletion or overwrites (see Storage and sharing for more information on how to do so). Be careful with the Clear Cache option (in Experimental features), as it removes all locally stored data including any stored Perspectives.
bloom app in neo4j desktop no server

With the Bloom server

This mode is useful for users who want the collaboration and persistent storage capabilities, but prefer a locally installed app. In this mode, the Bloom server component will be installed on the Neo4j database. The database can be locally created in Desktop, or in a remote server instance or cluster. When the Bloom client connects to the Neo4j database, it checks for the presence of the Bloom server plugin. If found, the Bloom client relies on the server to provide storage and user authorization capabilities. Perspectives can be stored alongside your business data in the property graph, or configured to store in a separate Neo4j instance.

bloom app in neo4j desktop

Even though the Bloom server can package and host the Bloom client, you may prefer to use your own web server and host the Bloom client separately from the Neo4j database server.

Bloom web app hosted by Neo4j database server

The Bloom server component package includes the Bloom client app. If the Bloom server is installed as a plugin to the database, then the Neo4j provided web server can also host the Bloom client so users can access it through a web browser. This setup is the easiest and most convenient to get started with server-hosted Bloom for users who will access the app via the web. It can be used for a single instance or a clustered setup of the Neo4j database.

neo4j hosted bloom client

Even though the Bloom server can package and host the Bloom client, you may prefer to use your own web server and host the Bloom client separately from the Neo4j database server. See Advanced Installation for this scenario.

 

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 file locations table 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.

 

Advanced installation and configuration

Bloom web app hosted in a separate web server

You may want to host the Bloom client on a separate web server, instead of on the Neo4j database server. This may be desirable for security reasons, or for load balancing reasons to separate the types of traffic directed at different types of servers. In this case, the Bloom client UI (provided as a separate package) will be hosted by your own web server, while the Bloom server plugin will still get installed on the Neo4j database (whether single instance or clustered setup).

web server hosted bloom client

For scenarios where you want to host Bloom client on a web server separate from the Neo4j database server, the Bloom client UI is available as a web asset bundle. Follow the steps below to set it up:

  1. Download the Bloom server package here.

  2. Unzip the downloaded Bloom server package. Look for a web asset bundle in the form of neo4j-bloom-<version>-assets.zip.

  3. Unzip and setup the files in the bundle to be served from your web server.

  4. Serve a json file containing Neo4j database discovery URL, which the Bloom client uses to connect to the intended Neo4j database server. The discovery URL is expected in the following format and saved as discovery.json in the root folder of your web server.

    {
	"bolt" : "bolt://<neo4j-database-server-address>:<bolt-port>"
}

    The asset bundle provided does include a discovery.json file. Modify the file provided to specify the correct Neo4j server and port information.

  5. Users should be able to access Bloom by loading the provided index.html in a web browser using your configured web server path.

Web server configuration

Neo4j has no specific recommendations about what web server to use for hosting the Bloom assets. Since it’s only serving static files it could be any web server that could be configured to do so (for example Apache, nginx, IIS). The only requirement is that it can handle the number of users, and thus the number of requests, you have. Bloom will make in the order of 10:s of requests per user per session.

If you have configured your Neo4j instance to only accept secured Bolt connections, you will need to configure the web server to serve the assets over https and make sure the needed TLS certificates are avaliable. Otherwise, Bloom may be unable to connect to Neo4j in many web browsers because of security policies that forbid mixing secured and unsecured connections.

This is an example configuration for the nginx web server:

user       www www;
worker_processes  1;  # If this nginx instance is the only thing running on this machine this can be set to number of cores

error_log  logs/error.log;
error_log  logs/error.log  notice;
error_log  logs/error.log  info;

pid        logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  my-bloom-domain;

        location / {
            root   /path/to/bloom/asset/files;
            index  index.html;
        }
    }

    # HTTPS server
    #
    #server {
    #    listen       443 ssl;
    #    server_name  my-bloom-domain;

    #    ssl_certificate      cert.pem;
    #    ssl_certificate_key  cert.key;

    #    ssl_session_cache    shared:SSL:1m;
    #    ssl_session_timeout  5m;

    #    ssl_ciphers  HIGH:!aNULL:!MD5;
    #    ssl_prefer_server_ciphers  on;

    #    location / {
    #        root   /path/to/bloom/asset/files;
    #        index  index.html;
    #    }
    #}
}

Using Bloom with LDAP authentication

In order to use Bloom with a Neo4j installation that uses LDAP authentication, Neo4j needs to be configured to use both native and LDAP authentication simultaneously. This is because the perspective sharing feature of Bloom requires the ability to list all the roles that are configured, and this is not possible when only using LDAP.

Enable both native and LDAP auth in neo4j.conf using the following configuration:

dbms.security.auth_providers=native,ldap

LDAP Example Scenario

Say the following users are defined in LDAP:

User Attributes

cn=Homer

memberOf: cn=bloom_group_1

memberOf: cn=bloom_reader

cn=Marge

memberOf: cn=bloom_group_2

memberOf: cn=bloom_reader

cn=Lisa

memberOf: cn=bloom_admin

The group to role mapping can be configured in neo4j.conf as follows:

dbms.security.ldap.authorization.group_to_role_mapping=   \
 "cn=bloom_group_1,dc=example,dc=com" = role_1;           \
 "cn=bloom_group_2,dc=example,dc=com" = role_2;           \
 "cn=bloom_admin,dc=example,dc=com"   = admin;            \
 "cn=bloom_reader,dc=example,dc=com"  = reader

Finally, the roles role_1 and role_2 will need to be created in the database (by using the dbms.security.createRole procedure).

Remember to authorize all the roles who will need Bloom access to the neo4j.bloom.authorization_role configuration property as described in the Installing server plugin section.

It should now be possible to log into Bloom with the user Lisa and create two perspectives, say Nuclear waste and Painting. If Lisa then assigns the Nuclear waste perspective to role_1 and Painting to role_2, the user Homer will get the Nuclear waste perspective when he logs in, but Marge will get the Painting perspective. See LDAP Integration section of the Operations manual to learn more about LDAP support in Neo4j.

Bloom Single Sign-On (SSO)

Bloom now provides basic support for some Single Sign On (SSO) providers under specific Enterprise environment configurations. Contact your Neo4j representative for additional assistance. Your organization needs an existing compatible SSO provider (local or external) already configured.

Supported providers at this time include OpenID Connect (OIDC) OAuth 2.0 providers Okta, KeyCloak, and Microsoft Azure AD. SSO has been tested on Neo4j 4.2.x and 4.3.x deployments. Bloom supports two authorization flows: * Authorization Code flow with PKCE * Implicit flow

It is strongly advised to use PKCE to ensure security. Further information about OpenID Connect and OAuth can be found at https://openid.net/connect/.

In addition to having an SSO provider already configured at your organization, configuring SSO for Bloom and Neo4j requires a separate OAuth plugin, available from your Neo4j representative. With these prerequisites in place, two additional steps are required:

  1. The neo4j.conf file should be updated with the following information (be sure to avoid duplicate entries in the neo4j.conf file):

    dbms.security.auth_enabled=true
dbms.security.authentication_providers=native,plugin-org.neo4j.auth.openid.OpenIdPlugin
dbms.security.authorization_providers=native,plugin-org.neo4j.auth.openid.OpenIdPlugin
plugins.auth.openid.configuration=https://login.org.com/.well-known/openid-configuration
plugins.auth.openid.group_to_role_mapping=reader=reader;editor=editor;publisher=publisher;architect=architect;admin=admin
plugins.auth.openid.claim.groups=groups
plugins.auth.openid.claim.principal=preferred_username

    Optionally, you may set extra logging for the OAuth2 plugin with these settings in the neo4j.conf file. The logs are found in the neo4j.log file.

    dbms.jvm.additional=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
dbms.jvm.additional=-Dorg.apache.commons.logging.simplelog.showdatetime=true
dbms.jvm.additional=-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG

  2. Bloom needs to be aware of the identity providers available for use, this can be done in two ways:

    1. Add information to Bloom’s discovery.json file located in your Bloom installation at the web root directory.

    2. Specify a URL parameter discoveryURL that specifies a URL to a json file containing the SSO providers. Example for Bloom: http://<bloom-server-host>:<http-port>?discoveryURL=http://webhost.com/public/discovery.json

The discovery.json file must contain entries tailored to your organization’s specific SSO solution. Below is a reference discovery file for the ID provider (IDP) Keycloak containing one SSO provider. It contains all the possible parameters you can provide. You most likely do not need all the parameters. If you are unsure, please consult your Neo4j representative to avoid misconfiguration.

{
	// other discovery entries
	// e.g. "bolt": "bolt://localhost:7687"
	//
	"sso_providers": [
	 {
			"id": "keycloak-oidc",  // has to be unique in this file!
			"name": "Keycloak", // displayed in UI
			"auth_flow": "pkce",
			"auth_endpoint": "http://localhost:18080/auth/realms/myrealm/protocol/openid-connect/auth",
			"token_endpoint": "http://localhost:18080/auth/realms/myrealm/protocol/openid-connect/token",
			"well_known_discovery_uri": "http://localhost:18080/auth/realms/myrealm/.well-known/openid-configuration",
			"params": {  // can be used for both the auth and the token request
				"client_id": "account",
				"redirect_uri": "http://localhost:8085?idp_id=keycloak-oidc&auth_flow_step=redirect_uri",
				"response_type": "code",  // depends on the auth_flow
				"scope": "openid groups"
			},
			"auth_params": { // optional
				"param_p": "<extra parameter used only for the auth request>"
			},
			"token_params": { // optional
				"client_secret": "<secret-here>", // this may be required by some Idp's and depended on the auth flow.
				"param_p": "<extra parameter used only for the token request>"
			},
			"config": { // optional settings, these allow you to overwrite the defaults
				"implicit_flow_requires_nonce": false, // Default: false; Desc: Specify if the implicit auth flow requries a nonce in the request
				"principal": "preferred_username",  // Default: email, otherwise sub; Desc: Optional, in which token claim the user's principal is specified
				"token_type_principal": "access_token" // Default: access_token; Desc: Which token type is decoded to acquire the specified principal
				"token_type_authentication": "access_token" // Default: access_token; Desc: Which token type is used as password
				"code_challenge_method": "S256" // Default is "S256" and it's the only supported method at this moment.
			}
		}
	]
}

redirect_uri MUST match exactly the redirect_uri specified in the IdP.

Deep links also work with SSO authentication, where available.

The following URL parameters support SSO in Bloom:

Table 1. URL parameters
URL (search parameter) Syntax Example Description

sso_redirect

sso_redirect=<idp_id>

sso_redirect=keycloak-oidc

Use to auto-redirect to SSO login page.

auth_flow_step

auth_flow_step=<arg>

auth_flow_step=redirect_uri

If the user arrives back to the client application with the URL param auth_flow_step=redirect_uri, this indicates that it is time to proceed in the auth process.

idp_id

idp_id=<idp_id>

idp_id=keycloak-oidc

The user arrives with a URL param named idp_id, mapped to the information in the discovery data to figure out how to proceed.

Installing Bloom in a Docker container

It is possible to install Bloom in a Docker container as well, using the standard Neo4j Enterprise Docker image. You can find all Neo4j Docker images here. For more information about the Neo4j Docker image, please see Operations Manual → Using the Neo4j Docker image.

Installing the Bloom plugin in a Docker container is only available with Neo4j Enterprise version 4.2.3 or later.

The Neo4j Docker image includes a startup script which automatically downloads and lets you configure the Bloom plugin at runtime, see Operations Manual → Configure Neo4j Labs plugins for more information.

Using the Bloom plugin requires a license, which can be provided as a shared volume in your Docker container:

docker run -it --rm \
  --publish=7474:7474 --publish=7687:7687 \
  -v $HOME/bloom.license:/licenses/bloom.license \
  --env NEO4J_AUTH=neo4j/test \
  --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
  --env NEO4JLABS_PLUGINS='["bloom"]' \
  neo4j:4.2.3-enterprise

Installing Bloom server in a database cluster

When setting up Bloom server in a database causal cluster, the Bloom plugin needs to be added to all the database instances, including core instances and read replicas.

In addition, if the cluster is also used to host the Bloom client, then pick any one instance within the cluster (all instances can serve Bloom) to be the designated Bloom-serving instance. Make sure HTTP or HTTPS is enabled and have users use that particular instance’s address in the URL. For example:

For Neo4j 3.x:
http://<cluster-instance-address>:<http-port>/browser/bloom/

https://<cluster-instance-address>:<https-port>/browser/bloom/
For Neo4j 4.x:
http://<cluster-instance-address>:<http-port>/bloom/

https://<cluster-instance-address>:<https-port>/bloom/
bloom in a neo4j cluster

If the Bloom client connects to a read replica in a causal cluster setup, write operations such as editing of a perspective, editing properties or creating nodes and relationships, will fail.

Storing Perspectives in a different database

If you prefer not to mix Perspective information with your other business data in the graph, the Bloom server can be configured to store Perspective information in a separate Neo4j database. In order to store perspectives in another Neo4j database, you have to specify bolt address and credentials required to connect to that database in the neo4j.conf configuration file as below. When used with a Neo4j 3.5 database, both bolt or bolt+routing protocols can be used.

This configuration is currently only available with the Bloom 3.x server plugin, i.e. when used with Neo4j 3.5 databases.

 
neo4.bloom.perspectiveStore=bolt://[host]:[port],[username],[password]
neo4.bloom.perspectiveStore=bolt+routing://[host]:[port],[username],[password]

This method requires the password to be stored in plain text in the neo4j.conf file. Please ensure only authorized individuals have access to the configuration file.