Configuration

This documentation pertains to the unsupported version of NeoDash, as part of Neo4j Labs. For users of the supported NeoDash offering, refer to NeoDash commercial.

When using a custom NeoDash deployment, there are several settings that can be configured. These mostly relate to Standalone Mode and SSO configurations.

For a simple (non-Dockerized) deployment, these configuration parameters can be changed by modifying dist/config.json after you have built the application. When Docker image, these can be passed as environment variables. See Standalone Mode for more on Docker deployments.

An example configuration for NeoDash (default, running in editor mode) will look like this:

{
    "ssoEnabled": false,
    "ssoProviders": [],
    "ssoDiscoveryUrl": "https://example.com",
    "standalone": false,
    "standaloneProtocol": "neo4j",
    "standaloneHost": "localhost",
    "standalonePort": "7687",
    "standaloneDatabase": "neo4j",
    "standaloneDashboardName": "My Dashboard",
    "standaloneDashboardDatabase": "dashboards",
    "standaloneDashboardURL": "",
    "standaloneAllowLoad": false,
    "standaloneLoadFromOtherDatabases": false,
    "standaloneMultiDatabase": false,
    "standaloneDatabaseList": "neo4j"
    "loggingMode": "0",
    "loggingDatabase": "logs",
    "customHeader": "",
}

Configuration Options

Name Type Default Value Description

Name	Type	Default Value	Description
ssoEnabled	boolean	false	If enabled, lets users connect to Neo4j using SSO. This requires a valid ssoDiscoveryUrl to be set.
ssoProviders	List	[]	When using multiple SSO providers on the database, you can configure the list of providers (by id) to be used on Neodash. If empty, all providers will be displayed.
ssoDiscoveryUrl	string	https://example.com	If ssoEnabled is true & standalone mode is enabled, the URL to retrieve SSO auth config from.
standalone	boolean	false	Determines whether to run NeoDash in editor mode (false), or reader mode (true). The terms `Reader mode'' and`Standalone mode'' are used interchangibly.
standaloneProtocol	string	neo4j	When running in standalone mode, the protocol to used for the Neo4j driver. This shoudl be set to one of `neo4j`, `neo4j+s`, `neo4j+ssc`, `bolt`, `bolt+s`, or `bolt+ssc`.
standaloneHost	string	localhost	When running in standalone mode, the hostname to connect to. This should be just the hostname, no protocols or ports.
standalonePort	string	7687	When running in standalone mode, the Bolt port to connect to.
standaloneDatabase	string	neo4j	When running in standalone mode, the database to use for reporting. Cypher queries used in reports will read data from this database.
standaloneUsername ⚠️	string	…	A hidden config parameter enables you to set the username for standalone mode by default. Keep in mind this is a security risk, as it exposes the Neo4j username to anyone who can access the NeoDash deployment.
standalonePassword ⚠️	string	…	A hidden config parameter enables you to set the password for standalone mode by default. If this value is set connections are also made automatically. Keep in mind this is a security risk, as it exposes the Neo4j username to anyone who can access the NeoDash deployment.
standaloneDashboardName	string	My Dashboard	The exact name (case-sensitive) of the dashboard to be loaded when running in standalone mode. This must be a dashboard that is saved as a node in the graph.
standaloneDashboardDatabase	string	neo4j	The name of the Neo4j database that contains the saved dashboard node. This is neo4j by default, unless you are using Neo4j Enterprise Edition, which lets you use multiple databases.
standaloneDashboardURL	string	neo4j	If you do not save a dashboard inside Neo4j and would like to run a standalone mode deployment with a dashboard from a URL, set this parameter to the complete URL pointing to the dashboard JSON.
standaloneAllowLoad	boolean	false	If set to yes the "Load Dashboard" button will be enabled in standalone mode, allowing users to load additional dashboards from Neo4J. This parameter is false by default unless you are using Neo4j Enterprise Edition, which lets you use multiple databases. NOTE: when Load is enabled in standalone mode, only Database is available as a source, not file.
standaloneLoadFromOtherDatabases	boolean	false	If standaloneAllowLoad is set to true, this parmeter enables or not users to load dashboards from other databases than the one deifned in standaloneDashboardDatabase. If standaloneAllowLoad is set to false this parameters has no effect.
standaloneMultiDatabase	boolean	false	If this parameter set to true, the standalone configuration will ignore the standaloneDatabase parameter and allow users to choose which database to connect to in the login screen, among the ones provided in standaloneDatabaseList, with a dropdown list. This parameter is false by default unless you are using Neo4j Enterprise Edition, which lets you use multiple databases.
standaloneDatabaseList	string	neo4j	If standaloneMultiDatabase is set to true, this parmeter must contain a comma separated list of database names that will be displayed as options in the Database dropdown at user login (e.g. 'neo4j,database1,database2' will populate the database dropdown with the values 'neo4j','database1' and 'database2' in the connection screen). If standaloneMultiDatabase is set to false this parameters has no effect.
loggingMode	string	none	Determines whether neodash should create any user activity logs. possible values include: `0` (no log is created), `1` (user login are tracked), `2` (tracks when a specific dashboard is accessed/loaded or saved by a user). ⚠️ Logs are created in Neo4J DB using the current user credentials (or standaloneUsername if configured); write access to the log database must be granted to enble any user to create logs. ⚠️ Load/Save from/to file are not logged (only from/to Database)
loggingDatabase	string	logs	When loggingMode is set to anything else than '0', the database to use for logging. Log records (nodes) will be created in this database.
customHeader	string	none	When set the dashboard header will display the prameter value as a fixed string, otherwise it will display the host and port of current connection.

ssoEnabled

boolean

false

If enabled, lets users connect to Neo4j using SSO. This requires a valid ssoDiscoveryUrl to be set.

ssoProviders

List

[]

When using multiple SSO providers on the database, you can configure the list of providers (by id) to be used on Neodash. If empty, all providers will be displayed.

ssoDiscoveryUrl

string

https://example.com

If ssoEnabled is true & standalone mode is enabled, the URL to retrieve SSO auth config from.

standalone

boolean

false

Determines whether to run NeoDash in editor mode (false), or reader mode (true). The terms Reader mode'' andStandalone mode'' are used interchangibly.

standaloneProtocol

string

neo4j

When running in standalone mode, the protocol to used for the Neo4j driver. This shoudl be set to one of neo4j, neo4j+s, neo4j+ssc, bolt, bolt+s, or bolt+ssc.

standaloneHost

string

localhost

When running in standalone mode, the hostname to connect to. This should be just the hostname, no protocols or ports.

standalonePort

string

7687

When running in standalone mode, the Bolt port to connect to.

standaloneDatabase

string

neo4j

When running in standalone mode, the database to use for reporting. Cypher queries used in reports will read data from this database.

standaloneUsername ⚠️

string

…

A hidden config parameter enables you to set the username for standalone mode by default. Keep in mind this is a security risk, as it exposes the Neo4j username to anyone who can access the NeoDash deployment.

standalonePassword ⚠️

string

…

A hidden config parameter enables you to set the password for standalone mode by default. If this value is set connections are also made automatically. Keep in mind this is a security risk, as it exposes the Neo4j username to anyone who can access the NeoDash deployment.

standaloneDashboardName

string

My Dashboard

The exact name (case-sensitive) of the dashboard to be loaded when running in standalone mode. This must be a dashboard that is saved as a node in the graph.

standaloneDashboardDatabase

string

neo4j

The name of the Neo4j database that contains the saved dashboard node. This is neo4j by default, unless you are using Neo4j Enterprise Edition, which lets you use multiple databases.

standaloneDashboardURL

string

neo4j

If you do not save a dashboard inside Neo4j and would like to run a standalone mode deployment with a dashboard from a URL, set this parameter to the complete URL pointing to the dashboard JSON.

standaloneAllowLoad

boolean

false

If set to yes the "Load Dashboard" button will be enabled in standalone mode, allowing users to load additional dashboards from Neo4J. This parameter is false by default unless you are using Neo4j Enterprise Edition, which lets you use multiple databases. NOTE: when Load is enabled in standalone mode, only Database is available as a source, not file.

standaloneLoadFromOtherDatabases

boolean

false

If standaloneAllowLoad is set to true, this parmeter enables or not users to load dashboards from other databases than the one deifned in standaloneDashboardDatabase. If standaloneAllowLoad is set to false this parameters has no effect.

standaloneMultiDatabase

boolean

false

If this parameter set to true, the standalone configuration will ignore the standaloneDatabase parameter and allow users to choose which database to connect to in the login screen, among the ones provided in standaloneDatabaseList, with a dropdown list. This parameter is false by default unless you are using Neo4j Enterprise Edition, which lets you use multiple databases.

standaloneDatabaseList

string

neo4j

If standaloneMultiDatabase is set to true, this parmeter must contain a comma separated list of database names that will be displayed as options in the Database dropdown at user login (e.g. 'neo4j,database1,database2' will populate the database dropdown with the values 'neo4j','database1' and 'database2' in the connection screen). If standaloneMultiDatabase is set to false this parameters has no effect.

loggingMode

string

none

Determines whether neodash should create any user activity logs. possible values include: 0 (no log is created), 1 (user login are tracked), 2 (tracks when a specific dashboard is accessed/loaded or saved by a user*).

⚠️ Logs are created in Neo4J DB using the current user credentials (or standaloneUsername if configured); write access to the log database must be granted to enble any user to create logs.

⚠️ * Load/Save from/to file are not logged (only from/to Database)

loggingDatabase

string

logs

When loggingMode is set to anything else than '0', the database to use for logging. Log records (nodes) will be created in this database.

customHeader

string

none

When set the dashboard header will display the prameter value as a fixed string, otherwise it will display the host and port of current connection.

Configuring SSO

NeoDash can use SSO as an alternative for password-based sign-in, if your Neo4j database is enabled to use single sign on. To enable SSO, set ssoEnabled to true. Then, set ssoDiscoveryUrl to the place where your discovery.json is located (This will often be the hostname of your database, appended by /discovery.json).

Note that SSO is only available when Standalone Mode is enabled.

Auth Provider

To set up NeoDash to use an external identity provider, you can add a /auth_provider resource to nginx (in /conf/default.conf):

location /auth_provider {
        default_type application/json;
        return 200 '{
                        "auth_config" : {
                            "oidc_providers" : [ ... ]
                        }
                    }';
    }

For basic deployments it might suffice to route requests to /auth_provider on the https port of the neo4j database.

Configuring Standalone Mode

Standalone mode, or reader-mode, overrides the functionality of NeoDash, allowing you to deploy a fixed dashboard to users. Standalone mode can be enabled by changing the standalone config parameter:

If standalone mode is false, all other configuration parameters are ignored. NeoDash will run in Editor mode, and require a manual sign-in.
If standalone mode is true, NeoDash will read all configuration parameters. A predefined dashboard will be auto-loaded, and no changes to the dashboard can be made. There are two types of valid standalone deployments:
- A standalone deployment that reads the fixed dashboard from Neo4j. The standaloneDashboardName and standaloneDashboardDatabase config parameters are used to define these.
- A standalone deployment that reads the fixed dashboard from a URL. The standaloneDashboardURL config parameter is used to define this.
Standalone mode can also be configured to allow users load a different dashboard after the predefined one is loaded (a Load Dashboard button will be displayed on the right side of dashboard title). The standaloneAllowLoad and standaloneLoadFromOtherDatabases are used to define this.
When allowing users to load dashboards dyamically in standalone mode, they may also need to connect to different databases, depending on the specific dashboard bing loaded. this can be enabled setting standaloneMultiDatabase to true and providing a comma separated list of the allowed database names in the`standaloneDatabaseList` parameter.