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:

Pass environment variables to the container (recommended for simple deployments).
Mount a config.yaml file as a volume (for complex configurations).

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, add --network host (port publishing is not needed with host networking):

docker run \
  --network host \
  -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://localhost: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://localhost:7474" \
  neo4j/enterprise-studio

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) or injected from a secrets manager at container startup, 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
    authentication:
      basic:
        username: my-service-user
        password: my-service-password

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:

docker run \
  -p 8080:8080 \
  -v /path/to/config.yaml:/app/config.yaml \
  -v /path/to/nes.license:/licenses/nes.license \
  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 \
  neo4j/enterprise-studio

Both approaches can be combined: mount a config file for base settings and use environment variables to override specific values (for example, injecting secrets from a secrets manager). Environment variables always take precedence over the mounted file.

TLS

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