Configuration

Enterprise Studio is configured through a config.yaml file. This file is included as a template in the binary distribution package, or built dynamically when using Docker or Kubernetes.

Minimal example

Enterprise Studio validates its configuration at startup and exits immediately if any required setting is missing. Ensure your configuration contains at least the following settings before first launch:

Config file (config.yaml)

version: 1
kind: neo4j-enterprise-studio-config

license:
  path: /licenses/nes.license          (1)

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687    (2)
    database: tools-storage            (3)
    authentication:
      basic:
        username: my-service-user      (4)
        password: my-service-password  (5)

neo4jDeployments:
  mydeployment:                        (6)
    name: My Neo4j                     (7)
    uri: http://my-neo4j-host:7474     (8)

1	Path to the Enterprise Studio license file. A valid license is required for Enterprise Studio to start.
2	URI of the Neo4j instance where Enterprise Studio stores its internal data.
3	Database on that instance to use for storage.
4	Service account user for asset storage.
5	Password for that user.
6	Unique identifier for this deployment (letters and digits only).
7	Human-readable label for the deployment.
8	Endpoint of the Neo4j instance that end users query through Enterprise Studio.

Environment file

The same minimal configuration can be expressed as an environment file (.env):

NES_server_port=8080
NES_license_path=/licenses/nes.license
NES_assetStore_default_uri=neo4j://my-neo4j-host:7687
NES_assetStore_default_database=tools-storage
NES_assetStore_default_authentication_basic_username=my-service-user
NES_assetStore_default_authentication_basic_password=my-service-password
NES_neo4jDeployments_mydeployment_name=My Neo4j
NES_neo4jDeployments_mydeployment_uri=http://my-neo4j-host:7474

Pass this file to Docker with the --env-file flag:

docker run -p 8080:8080 --env-file .env \
  europe-west1-docker.pkg.dev/dev-upx/enterprise-studio/neo4j-enterprise-studio

See Environment variable overrides for the full naming scheme.

Asset store

Enterprise Studio persists tool assets (dashboards, saved queries, Perspectives) in a dedicated Neo4j database. Configure the connection to this database under assetStore.default:

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage
    authentication:
      basic:
        username: studio-service
        password: secret

database: Name of the database used for storage. This database must already exist — create it before starting Enterprise Studio (see Prerequisites → Set up the tool asset database).
authentication: Authentication method for the storage connection. Configure exactly one method block: basic (username/password), oidc (OAuth 2.0 client-credentials grant), or none (no authentication).

For OIDC-based authentication to the storage database, see the OIDC fields in the reference.

Neo4j Deployments

A deployment represents a Neo4j instance that end users connect to through Enterprise Studio. At least one deployment must be defined.

By default, Enterprise Studio proxies queries to Neo4j on behalf of the user. In this mode, uri must point to the Neo4j HTTP API (typically port 7474 for HTTP or 7473 for HTTPS), because the server translates user queries into HTTP API requests:

HTTPS (default proxy mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: https://neo4j-prod:7473

Bolt (direct client query mode)

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687

In proxy mode, uri points to the Neo4j HTTP API (port 7474 / 7473). In direct client query mode, uri uses the Bolt protocol (port 7687).

Direct client query

Alternatively, you can let the user’s browser connect directly to Neo4j by enabling directClientQuery. In this mode, uri must use a Bolt scheme (neo4j://, neo4j+s://, bolt://, or bolt+s://) because the browser communicates with Neo4j over the Bolt protocol (typically port 7687). You must also provide a publicUri that is reachable from the end user’s browser:

neo4jDeployments:
  production:
    name: Production Graph
    uri: neo4j+s://neo4j-prod:7687
    directClientQuery:
      enabled: true
      publicUri: neo4j+s://neo4j.example.com:7687

uri: Internal URI used by the server. Not required to be publicly accessible.
directClientQuery.publicUri: Public URI that end-user browsers connect to directly. Must be reachable from the user’s network.

Authentication methods

By default, end users can sign in to a deployment with either username/password (basic) or single sign-on through an OIDC identity provider (oidc). Use authentication to restrict which methods are offered in the connection form:

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authentication:
      basic:
        enabled: false  (1)

1	Disable username/password sign-in.

Each method is enabled by default when omitted.

Authorization

Map Neo4j database users or roles to Enterprise Studio roles to control who can administer or create content. See Administration for a full walkthrough of role assignment by database role, username, or SSO.

neo4jDeployments:
  production:
    name: Production Graph
    uri: http://neo4j-prod:7474
    authorization:
      roleMapping:
        - role: studioAdmin
          members:
            - kind: databaseUser
              name: neo4j
            - kind: databaseRole
              name: admin
        - role: studioCreator
          members:
            - kind: databaseRole
              name: editor

Server

By default, Enterprise Studio listens on HTTP port 8080.

server:
  port: 9090                            (1)
  https:
    enabled: true                       (2)

1	Change the listen port.
2	Enable HTTPS. Requires TLS certificates; see TLS below.

TLS

Clients send their Neo4j credentials (username/password or bearer token) to Enterprise Studio on every request. Without TLS, those credentials travel in cleartext and can be intercepted. Always serve Enterprise Studio over HTTPS in production, either by enabling server.https.enabled or by terminating TLS at a trusted reverse proxy or load balancer in front of it.

When server.https.enabled is false, Enterprise Studio prints a reminder at startup. See Security → TLS encryption for guidance.

When server.https.enabled is true, place certificate files in the directory specified by server.https.certificates.baseDirectory (default: certificates/https relative to the installation home). These settings configure inbound HTTPS only; outbound trust to Neo4j is separate — see Security → TLS encryption and Binary deployment.

server:
  https:
    enabled: true
    certificates:
      baseDirectory: /etc/studio/certs  (1)
      privateKey: private.key           (2)
      publicCertificate: public.crt     (3)

1	Absolute or relative path to the certificate directory.
2	Unencrypted PKCS#8 PEM private key file.
3	PEM public certificate file.

See TLS encryption for a step-by-step guide.

Tools

Individual tools can be disabled if not needed:

tools:
  dashboards:
    enabled: true
  bloom:
    enabled: true
  query:
    enabled: false

Set enabled to false to hide a tool from the UI. All tools are enabled by default.

Enterprise Studio reads tool configuration only at startup. Restart the server after changing any tools.*.enabled setting for the change to take effect.

Logging

logs:
  level: info
  format: json

level: Log verbosity. One of debug, info, warn, or error.
format: Log output format. Use json (recommended for production) or pretty (human-readable, useful during development).

Environment variable overrides

Any setting in config.yaml can be overridden by setting an environment variable. This is useful for injecting secrets or adjusting values per environment without modifying the config file.

To derive the environment variable name from a config path:

Start with the prefix NES_
Replace each . with _
Keep camelCase as-is

Table 1. Examples
Config path	Environment variable
`assetStore.default.uri`	`NES_assetStore_default_uri`
`server.port`	`NES_server_port`
`server.https.enabled`	`NES_server_https_enabled`
`neo4jDeployments.mydeployment.uri`	`NES_neo4jDeployments_mydeployment_uri`

Deployment IDs must contain only letters and digits (a-z, A-Z, 0-9). This keeps them safe to use directly in NES_neo4jDeployments_<id>_… environment variable names.

For example, to override the asset storage URI and server port:

export NES_assetStore_default_uri="neo4j://my-host:7687"
export NES_server_port="9090"

Environment variables override values in config.yaml at runtime: they do not modify the file on disk. See the Docker deployment page for a complete example using environment variables.