Harmony Docker Container: Build & Run Guide

This document explains how to build and run the Docker container that installs the Harmony programming language via pip, along with required system dependencies (Python, Graphviz, and a C toolchain).

Prerequisites

If you see an error like “Cannot connect to the Docker daemon…”, it usually means Docker Desktop is not running yet.

1) Build the image

From the directory that contains the Dockerfile, run: 

docker build -t harmony .

This will produce a local image named harmony.

2) Run the container interactively

The following commands start the container and mount your current directory into /work inside the container.

macOS / Linux

docker run --rm -it -v "$(pwd)":/work harmony

Windows (PowerShell)

docker run --rm -it -v ${PWD}:/work harmony

Flags explained: --rm remove container on exit, -it interactive terminal, -v bind-mount your project into the container.

3) Verify the installation inside the container

Once you are inside the container (you should see a shell prompt), you can run the following checks: 

# Show what pip installed
python -m pip show harmony

# List files installed by the distribution (useful when the import name differs)
python -m pip show -f harmony | sed -n '1,200p'

# Confirm Graphviz is available
dot -V

# Confirm a C compiler is available (required by Harmony or its native deps)
gcc --version

Depending on how the Harmony PyPI distribution is packaged, the Python import name may not be harmony. If there is a CLI entrypoint, it will usually appear in /usr/local/bin. 

# Look for Harmony-related commands
ls -la /usr/local/bin | grep -i harm

4) Running Harmony on your mounted code

Because your host directory is mounted at /work, you can reference files there directly from inside the container. 

cd /work
ls -la

Run the Harmony CLI command you discovered (for example, harmony, or another Harmony-related binary shown by the grep step). If you want the container to execute that command by default, update the Dockerfile’s CMD accordingly.

Troubleshooting

Docker daemon not running

Symptom: “Cannot connect to the Docker daemon … Is the docker daemon running?” Start Docker Desktop and re-run the command.

Harmony installs but cannot be imported

Symptom: ModuleNotFoundError: No module named 'harmony'. The PyPI distribution name can differ from the import name. Use: 

python -m pip show -f harmony
python -c "import pkgutil; print([m.name for m in pkgutil.iter_modules() if 'harm' in m.name.lower()])"
ls -la /usr/local/bin | grep -i harm

Native build failures

If pip install harmony fails with compiler/linker errors, ensure the image includes a full build toolchain (this container installs build-essential and make). Some packages may additionally require specific -dev libraries; the error message will usually indicate which one.