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 (the compose file lives at 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. Pin image versions for the second stand. Any tag from Docker Hub is valid — see Images and versions for the latest pinned set, or release history for older releases.

    Each service has its own environment variable: DATAGROK_VERSION, GROK_PIPE_VERSION, GROK_SPAWNER_VERSION, GROK_CONNECT_VERSION, JKG_VERSION, GROK_REGISTRY_PROXY_VERSION. They all default to bleeding-edge. To pin a stand to the latest stable release:

    set DATAGROK_VERSION=1.27.3
    set GROK_PIPE_VERSION=1.19.0
    set GROK_SPAWNER_VERSION=2.16.0
    set GROK_CONNECT_VERSION=2.6.2
    set JKG_VERSION=1.31.0

  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
    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

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​