Deploy with Docker

Before deploying Enterprise Studio, ensure you have completed the prerequisites for your Neo4j deployment(s).

For every Enterprise Studio release, a Docker image is published to Docker Hub. To pull the latest image, run the following command:

docker pull neo4j/enterprise-studio:latest

Configuration

There are two ways to configure Enterprise Studio in Docker:

Using environment variables

The Docker image ships with a default config.yaml inside the container. You can override any setting by passing environment variables with the NES_ prefix when running the container.

Run Enterprise Studio with the minimum required configuration supplied as environment variables:

docker run \
  -p 8080:8080 \
  -v /path/to/nes.license:/licenses/nes.license \
  -e NES_license_path="/licenses/nes.license" \
  -e NES_server_port="8080" \
  -e NES_assetStore_default_uri="neo4j://my-neo4j-host:7687" \
  -e NES_assetStore_default_database="tools-storage" \
  -e NES_assetStore_default_authentication_basic_username="my-service-user" \
  -e NES_assetStore_default_authentication_basic_password="my-service-password" \
  -e NES_neo4jDeployments_mydeployment_name="My Neo4j" \
  -e NES_neo4jDeployments_mydeployment_uri="http://my-neo4j-host:7474" \
  neo4j/enterprise-studio

A valid license is required at startup, so the license file is mounted into the container and NES_license_path points to it. The -p 8080:8080 flag publishes the container port so Enterprise Studio is accessible from outside the container. If your Neo4j deployment is running on the host machine, additional network parameters may be needed depending on your OS, see Docker networking.

See Environment variable overrides for the complete naming scheme including handling of special characters in deployment IDs.

Environment variables override values in the bundled config.yaml file at runtime: they do not modify the file on disk. See Environment variable overrides for the full naming scheme.

Sensitive configuration values (passwords, client secrets) should be supplied via environment variables (-e) rather than stored in config.yaml.

Using a mounted config file

For more complex configurations, you can mount a config.yaml file into the container. Enterprise Studio validates the configuration at startup and the container will exit immediately if any required property is missing. See Minimum required configuration for the full list of properties you must set before first launch.

Create a config.yaml with at least the required settings:

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

license:
  path: /licenses/nes.license

assetStore:
  default:
    uri: neo4j://my-neo4j-host:7687
    database: tools-storage

neo4jDeployments:
  mydeployment:
    name: My Neo4j
    uri: http://my-neo4j-host:7474

The license.path above is a path inside the container, so the license file must be mounted there (see the -v flags below).

Run the container and mount the file with the -v flag. You can override secrets with -e instead of storing them in the mounted file:

docker run \
  -p 8080:8080 \
  -v /path/to/config.yaml:/app/config.yaml \
  -v /path/to/nes.license:/licenses/nes.license \
  -e NES_assetStore_default_authentication_basic_password="my-service-password" \
  -e NES_assetStore_default_authentication_basic_username="my-service-user" \
  neo4j/enterprise-studio

If your Neo4j deployment is running on the host machine, use --network host so the container can reach it:

docker run \
  --network host \
  -v /path/to/config.yaml:/app/config.yaml \
  -v /path/to/nes.license:/licenses/nes.license \
  -e NES_assetStore_default_authentication_basic_password="my-service-password" \
  -e NES_assetStore_default_authentication_basic_username="my-service-user" \
  neo4j/enterprise-studio

Both approaches can be combined: mount a config file for base settings and use environment variables to override specific values. Environment variables always take precedence over the mounted file.

Local Docker setup

If your Neo4j deployment is running on the same machine as Docker, ensure Enterprise Studio can reach your local database.

Linux

Add --network host and use localhost in the URIs:

docker run \
  --network host \
  -e NES_assetStore_default_uri="neo4j://localhost:7687" \
  -e NES_neo4jDeployments_mydeployment_uri="http://localhost:7474" \
...

macOS and Windows

Omit --network host, publish the port with -p 8080:8080, and replace localhost with host.docker.internal. Also set dbms.default_listen_address=0.0.0.0 in the Neo4j instance’s neo4j.conf so it accepts connections from host.docker.internal.

docker run \
  -p 8080:8080 \
  -e NES_assetStore_default_uri="neo4j://host.docker.internal:7687" \
  -e NES_neo4jDeployments_mydeployment_uri="http://host.docker.internal:7474" \
...

Cloud Secrets Managers

If config.yaml uses Secrets Manager references (usernameFrom, passwordFrom, or clientSecretFrom), give the container cloud credentials through the provider’s default credential chain — do not put access keys in config.yaml. Secret shape and required permissions are covered under Configuration → Secrets Manager. For Kubernetes, see Deploy to Kubernetes → Cloud Secrets Managers.

In production, use an attached identity on the host — no credential files need to be mounted. For local development, sign in with the cloud CLI on the host, then mount the credential directory into the container.

Provider Production identity Local / development

AWS

EC2 instance profile or ECS task role

CLI login on the host, then mount $HOME/.aws

Azure

Azure managed identity

az login on the host, then mount $HOME/.azure

Google Cloud

Attached service account

gcloud auth application-default login on the host, then mount ADC

TLS

Inbound TLS (HTTPS)

Always enable TLS for production deployments. To enable HTTPS, mount your certificate directory and set the environment variable:

  -v /path/to/certs:/app/certificates/https:ro \
  -e NES_server_https_enabled="true"

The directory must contain public.crt and private.key. Add these flags to any of the docker run commands above. For certificate format requirements, key conversion, and backend TLS configuration, see Security → TLS.

Outbound TLS trust (private CAs)

When Neo4j deployments or asset storage use HTTPS or Bolt+TLS with a private CA, Enterprise Studio must trust that CA to connect successfully. Trust is installed in the container system trust store if located under /etc/ssl/certs, or SSL_CERT_DIR if set.

Mount the CA certificate on the docker container:

docker run \
  -p 8080:8080 \
  -v ./ca.crt:/etc/ssl/certs/ca.crt \
  -v /path/to/nes.license:/licenses/nes.license \
  -e NES_license_path="/licenses/nes.license" \
  -e NES_server_port="8080" \
  -e NES_assetStore_default_uri="neo4j+s://my-neo4j-host:7687" \
  -e NES_assetStore_default_database="tools-storage" \
  -e NES_assetStore_default_authentication_basic_username="my-service-user" \
  -e NES_assetStore_default_authentication_basic_password="my-service-password" \
  -e NES_neo4jDeployments_mydeployment_name="My Neo4j" \
  -e NES_neo4jDeployments_mydeployment_uri="https://my-neo4j-host:7473" \
  neo4j/enterprise-studio:latest

Combine with a mounted config.yaml by adding -v /path/to/config.yaml:/app/config.yaml if needed. See Environment variable overrides for the full NES_ naming scheme.

Health check

Enterprise Studio exposes a GET /health endpoint that returns 200 OK when the server is running. Use it as a Docker health check:

docker run \
  -p 8080:8080 \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 15s \
  --health-start-period 10s \
  -v /path/to/config.yaml:/app/config.yaml \
  -v /path/to/nes.license:/licenses/nes.license \
  neo4j/enterprise-studio