Chapter 3. Installation

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.

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.

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.

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.

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.

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.

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

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.

http://<neo4j-server-host>:<http-port>/browser/bloom/

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

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

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

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).

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:

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;
    #    }
    #}
}

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:

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.

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/

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 database 3.4 or 3.5, both bolt or bolt+routing protocols can be used.

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