Skip to main content

Local machine: advanced

For most users the Local machine install script is enough. This page covers running the canonical compose file docker/localhost.docker-compose.yaml directly: selectively starting service profiles, running multiple stands side by side, attaching the demo databases, and troubleshooting.

The same Datagrok services run on every deployment — see Components for the canonical list.

Hardware requirements

Minimal: 60 GB of free disk space, 4 CPUs, 8 GB RAM.

Prerequisites​

  1. Install and launch the latest Docker Desktop:

  2. Clone the public repository and check out the branch for the release you want to run (the compose file lives at docker/localhost.docker-compose.yaml):

    git clone --branch release/1.27.7 https://github.com/datagrok-ai/public.git

    The branch matters. A compose file and the images it starts are versioned together, so master's compose file is bound to bleeding-edge images and will not work against a stable release — see configuration is versioned with the image. Each compose file states which release it belongs to in its top-level x-datagrok-release field:

    grep x-datagrok-release docker/localhost.docker-compose.yaml

  3. Open a terminal and cd into the cloned repository.

Compose profiles​

The compose file uses Docker Compose profiles to start subsets of services. The all profile is everything; pick narrower profiles to save disk and RAM.

ProfileStarts
allEvery Datagrok service plus the in-cluster Postgres
datagrokDatagrok core only
dbIn-cluster Postgres
grok_connectGrok Connect (external database connectors)
grok_spawnerGrok Spawner (manages plugin containers)
rabbitmqRabbitMQ (AMQP queue, required for scripting)
scripting / jkgJupyter Kernel Gateway, RabbitMQ, grok_pipe — server-side script execution
cvmConvenience alias for scripting + everything it needs
mlflow / mlMLflow tracking server and supporting Postgres
demoDemo databases (world, chembl, northwind, unichem, starbucks) — used by tutorials
postgres_chembl, postgres_world, ...Individual demo databases
postgres_rdkitAdds RDKit Postgres for cheminformatics work

Install Datagrok​

  1. Pull the latest images:

    docker compose -f docker\localhost.docker-compose.yaml --profile all pull

  2. Start the full stack:

    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all up -d
    note

    If you encounter an error related to a WriteFile function when running docker-compose up on Windows, try running the command prompt (cmd) in Administrator mode. This is a known issue with Docker on certain computers.

  3. After about a minute the server is ready at http://localhost:8080. Sign in as admin / admin.

Selective profiles​

Drop scripting/JKG to save disk and RAM:

docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
  --profile datagrok --profile db --profile grok_connect --profile grok_spawner up -d

Add server-side scripting (Python / R / Julia / JavaScript / Octave) on top:

docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
  --profile datagrok --profile db --profile grok_connect --profile grok_spawner ^
  --profile scripting up -d

The scripting profile pulls in RabbitMQ, grok_pipe, and the Jupyter Kernel Gateway — everything needed for server-side scripts.

Demo databases​

Datagrok ships with demo databases that back several tutorials. Add them with the demo profile:

docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
  --profile all --profile demo up -d

Use individual postgres_<name> profiles to start a single demo database.

Multiple stands​

You can run more than one Datagrok stand on the same host. To do so, give the second stand a different project name and override the host ports it binds.

  1. Run the first stand as described above (project name datagrok).

  2. Run the second stand from a different release if you need one. The reliable way is a second checkout on that release's branch — each branch's compose file already defaults every image to the right tag, so there is nothing to set:

    git clone --branch release/1.27.6 https://github.com/datagrok-ai/public.git public-1.27.6

    Every image tag is also individually overridable, for testing a single service against the rest of a stand:

    Environment variableOverrides
    DATAGROK_VERSIONdatagrok/datagrok
    GROK_PIPE_VERSIONdatagrok/grok_pipe
    GROK_SPAWNER_VERSIONdatagrok/grok_spawner
    GROK_CONNECT_VERSIONdatagrok/grok_connect
    GROK_CONNECT_ADBC_VERSIONdatagrok/grok_connect_adbc
    JUPYTER_KERNEL_GATEWAY_VERSIONdatagrok/jupyter_kernel_gateway
    caution

    Overriding these opts out of the release binding. DATAGROK_VERSION in particular changes the server image but not the GROK_PARAMETERS in the compose file, and a server given configuration from another release can fail to start. To run a different release, take its compose file too.

  3. Override the host ports the second stand binds. Pick values that don't collide with the first stand:

    Environment variableDefault
    DATAGROK_PORT8080
    DATAGROK_DB_PORT5432
    GROK_SPAWNER_PORT8000
    GROK_CONNECT_PORT1234
    GROK_CONNECT_ADBC_PORT1235
    RABBITMQ_PORT5672
    RABBITMQ_MANAGEMENT_PORT15672
    DATAGROK_DEMO_POSTGRES_NORTHWIND_PORT5433
    DATAGROK_DEMO_POSTGRES_CHEMBL_PORT5434
    DATAGROK_DEMO_POSTGRES_UNICHEM_PORT5435
    DATAGROK_DEMO_POSTGRES_STARBUCKS_PORT5436
    DATAGROK_DEMO_POSTGRES_WORLD_PORT5437

  4. Start the second stand under a different project name (e.g. datagrok_2):

    set DATAGROK_PORT=8091
    set DATAGROK_DB_PORT=5443
    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok_2 ^
      --profile all up -d

Compose variants​

Several alternative compose files cover specific cases:

FileUse when
docker/localhost.docker-compose.yamlDefault local install
docker/localhost.bleeding-edge.docker-compose.yamlTrack latest unreleased images
docker/localhost.bleeding-edge-separate-data.docker-compose.yamlBleeding-edge with persistent data volumes detached
docker/localhost.macos-silicon.docker-compose.yamlApple Silicon (ARM64); pulls linux/arm64 image variants
docker/localhost.js-api.debug.docker-compose.yamlJS API debugging with source maps — an overlay, see below

The JS API debug file overrides the datagrok service to bind-mount a locally built js-api and is not a stack on its own. Pass it after the base file:

docker compose -f docker/localhost.docker-compose.yaml \
  -f docker/localhost.js-api.debug.docker-compose.yaml \
  --project-name datagrok --profile all up -d

Shutting down Datagrok​

Stop the containers (volumes preserved):

docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
  --profile all --profile demo stop

Reset to factory state — removes all data including users, projects, and connections:

docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
  --profile all --profile demo down --volumes

Troubleshooting​

  1. View logs (follow live):

    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all logs -f --tail 200 datagrok

    Replace datagrok with any service: db, grok_connect, grok_pipe, grok_spawner, jupyter_kernel_gateway, rabbitmq, etc.

  2. Open a shell inside a container:

    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all exec datagrok /bin/sh

  3. Recreate the stand from scratch:

    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all --profile demo down --volumes
    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all --profile demo pull
    docker compose -f docker\localhost.docker-compose.yaml --project-name datagrok ^
      --profile all --profile demo up -d

  4. Docker logs may consume free disk space over time. Limit the daemon's log size via Docker Desktop resource settings or the logging configuration.

See also​