Dockerize (#578)

Co-authored-by: Gary Miller <gary@helixcollective.com>
Co-authored-by: Patrick Dubroy <pdubroy@gmail.com>

Author: 3 people

.dockerignore

@@ -0,0 +1,13 @@
+Dockerfile
+**/node_modules
+**/node_modules/**
+docker-compose.yml
+docker-compose.dev.yml
+doc/**
+.dockerignore
+**/build
+**/dist
+packages/compiler/test/go/testmain
+
+# committed to repo - see 'git ls-files packages/ohm-js/dist'
+!packages/ohm-js/dist

.github/workflows/node.js.yml

@@ -24,5 +24,7 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v2
+        with:
+          version: 10
       - run: pnpm install
       - run: pnpm ci-test

.github/workflows/publish-preview.yml

@@ -17,6 +17,8 @@ jobs:
         with:
           node-version: 22
       - uses: pnpm/action-setup@v2
+        with:
+          version: 10
       - run: pnpm install
       - run: pnpm build
       - run: pnpm dlx pkg-pr-new publish './packages/compiler' './packages/runtime' './packages/to-ast-compat'

README.md

@@ -37,6 +37,16 @@ The easiest way to get started with Ohm is to use the [interactive editor](https
 - For community support and discussion, join us on [Discord](https://discord.gg/KwxY5gegRQ), [GitHub Discussions](https://github.com/ohmjs/ohm/discussions), or the [ohm-discuss mailing list](https://groups.google.com/u/0/g/ohm-discuss).
 - For updates, follow on [Bluesky](hhttps://bsky.app/profile/ohmjs.org) or [Mastodon](https://hachyderm.io/@ohmjs).
 
+### Docker
+
+You can use the Ohm CLI without a local Node.js installation via the Docker image:
+
+```sh
+docker run --rm -v $(pwd):/local ohmjs/ohm:latest compile my-grammar.ohm
+```
+
+For full usage instructions, including how to build the image locally and set up a development container, see [doc/docker.md](doc/docker.md).
+
 ### Installation
 
 #### On a web page

doc/docker.md

@@ -0,0 +1,159 @@
+# Using Ohm.js with Docker
+
+The `ohm:latest` image provides the Ohm compiler CLI in a self-contained environment — no local Node.js or pnpm installation required.
+
+## Commands overview
+
+| Command           | Description |
+|-------------------|-------------|
+| `compile`         | Compile an `.ohm` grammar file to a `.wasm` module |
+| `generateBundles` | Generate grammar bundles (currently not working) |
+| `shell`           | Open a bash shell inside the container |
+| `help`            | Print usage information |
+
+Your current directory is mounted at `/local` inside the container, so relative paths to grammar files work as expected.
+
+---
+
+## 1. Running
+
+Pull and run the image directly from Docker Hub:
+
+```sh
+docker run --rm -v $(pwd):/local ohmjs/ohm:latest compile my-grammar.ohm
+```
+
+### `compile` usage
+
+```sh
+docker run --rm -v $(pwd):/local ohmjs/ohm:latest compile [options] <grammar-file>
+```
+
+Options:
+
+| Flag                          | Description |
+|-------------------------------|-------------|
+| `--debug` / `-d`              | Enable debug output |
+| `--grammarName` / `-g <name>` | Override the grammar name |
+| `--output` / `-o <file>`      | Write output to `<file>` instead of `<grammar-file>.wasm` |
+
+**Example** — compile `arithmetic.ohm` and write the result to `arithmetic.wasm`:
+
+```sh
+docker run --rm -v $(pwd):/local ohmjs/ohm:latest compile -o arithmetic.wasm arithmetic.ohm
+```
+
+### Getting help
+
+```sh
+docker run --rm ohmjs/ohm:latest help
+```
+
+---
+
+## 2. Development
+
+### Minimal Docker setup for macOS
+
+```sh
+brew install colima docker docker-compose docker-credential-helper
+colima start
+```
+
+Add to `~/.docker/config.json`:
+
+```json
+{
+  "cliPluginsExtraDirs": [
+    "/opt/homebrew/lib/docker/cli-plugins"
+  ]
+}
+```
+
+> **Note:** If you see `docker-credential-desktop` errors, remove `"credsStore": "desktop"` from `~/.docker/config.json` — it references Docker Desktop, which isn't needed with Colima.
+
+### Building the image locally
+
+Clone the repository and build the production image with Docker Compose:
+
+```sh
+git clone https://github.com/ohmjs/ohm.git
+cd ohm
+docker compose -f docker/docker-compose.yml build
+```
+
+This builds the `ohm:latest` image using the `dist` stage of the multi-stage `Dockerfile`, which produces a slim image containing only the compiled packages and their production dependencies.
+
+The `ohm:latest` image is 664 MB and is 99% space efficient (per `wagoodman/dive`).
+
+### Building a development image
+
+The development image uses the `build` stage of the `Dockerfile`, which includes the full source tree, all dev dependencies, and the complete build output. This is useful for iterating on the compiler or debugging build issues.
+
+**Build:**
+
+```sh
+TARGET=build docker compose -f docker/docker-compose.yml build
+```
+
+This produces the `ohmjs/ohm:development` image.
+
+**Run:**
+
+```sh
+docker run -v $(pwd):/local -it --rm ohmjs/ohm:development shell
+# or
+docker run -v ${PWD}:/local -it --rm ohmjs/ohm:development shell
+```
+
+The `-v $(pwd):/local` mount makes your current directory available at `/local` inside the container. The `shell` command drops you into a bash session where you can inspect the built artifacts under `/ohm/` or run CLI commands directly.
+
+The `ohm-dev:latest` images is 1.62 GB and is 97% efficient with only 64 MB potentially wasted space.
+
+### Publishing to Docker Hub
+
+Build and push a versioned image to Docker Hub using the git tag as the version:
+
+```sh
+# if not set default to ohmjs (ie docker hub using the ohmjs org)
+export DOCKER_REPO=<custom docker repo>
+# if not set defaults to 'development'
+export VERSION=$(cat packages/runtime/package.json | jq -r '.version')
+# or export VERSION=$(git describe --tag --dirty)
+
+# # it might be necessary (particularly on osx) to create a new builder
+# # the default builder might not support multi-platform builds
+# docker buildx create --use --name ohmjs-builder
+# # might be needed
+# docker buildx inspect --bootstrap
+# # or if already created
+# docker buildx use ohmjs-builder
+
+# generate a person access token at https://app.docker.com/accounts/millergarym/settings/personal-access-tokens
+# assuming DHPAT contains your PAT
+echo $DHPAT | docker login -u <personal username> --password-stdin
+docker buildx bake --push
+```
+
+`git describe --tag --dirty` produces a version string based on the nearest git tag, appending commit info and a `-dirty` suffix if there are uncommitted changes.
+
+The defaults in `docker-compose.yml` are `DOCKER_REPO=ohmjs` and `VERSION=development`. See [docker-compose.yml](../docker/docker-compose.yml) for details.
+
+## Tips and Tricks
+
+### Image size
+
+To track down file which can be deleted.
+
+**From inside the container**
+```sh
+apt-get update
+apt-get install -y ncdu
+ncdu /
+```
+
+**Analysing the images**
+```sh
+alias dive="docker run -ti --rm  -v /var/run/docker.sock:/var/run/docker.sock docker.io/wagoodman/dive"
+dive ohmjs/ohm:latest
+```

docker/Dockerfile

@@ -0,0 +1,48 @@
+FROM node:24 AS build
+
+RUN npm install -g pnpm@latest-10
+
+WORKDIR /ohm
+COPY package.json pnpm-lock.yaml ./
+RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
+  CI=true pnpm fetch
+
+COPY . /ohm
+
+RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
+  CI=true pnpm install --frozen-lockfile --offline && \
+  CI=true pnpm build
+
+ENTRYPOINT [ "/ohm/docker/entrypoint.sh" ]
+
+CMD ["help"]
+
+FROM node:24-slim AS dist
+
+RUN npm install -g pnpm@latest-10
+
+WORKDIR /ohm
+
+COPY package.json pnpm-lock.yaml ./
+COPY docker/pnpm-workspace.yaml ./pnpm-workspace.yaml
+RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
+  CI=true pnpm fetch --prod
+
+COPY --from=build /ohm/packages/ohm-js          /ohm/packages/ohm-js
+COPY --from=build /ohm/packages/runtime         /ohm/packages/runtime
+COPY --from=build /ohm/packages/to-ast-compat   /ohm/packages/to-ast-compat
+COPY --from=build /ohm/packages/compiler        /ohm/packages/compiler
+COPY --from=build /ohm/packages/semantics       /ohm/packages/semantics
+COPY --from=build /ohm/packages/lang-python     /ohm/packages/lang-python
+COPY --from=build /ohm/packages/cli             /ohm/packages/cli
+
+# Note:
+#  The build stage fetched all dependencies, where as the dist stage only fetches production dependencies.
+#  This means that some symlinks, copied from the build stage, will be broken in the dist stage.
+#  Safely remove all broken symlinks.
+RUN find /ohm/packages -xtype l | xargs rm
+
+COPY ./docker/entrypoint.sh entrypoint.sh
+ENTRYPOINT [ "/ohm/entrypoint.sh" ]
+
+CMD ["help"]

docker/docker-compose.yml

@@ -0,0 +1,26 @@
+name: ohmjs
+
+services:
+
+  ohm:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      tags:
+        - ${DOCKER_REPO:-ohmjs}/ohm:latest
+        - ${DOCKER_REPO:-ohmjs}/ohm:${VERSION:-development}
+      labels:
+        - org.opencontainers.image.source=https://github.com/${OWNER:-ohmjs}/${REPO:-ohm}
+        - org.opencontainers.image.licenses=MIT
+        - org.opencontainers.image.description=Ohm tooling - A library and language for building parsers, interpreters, compilers, etc.
+      x-bake:
+        platforms:
+          - linux/amd64
+          # - linux/arm/v7
+          - linux/arm64/v8
+          # - linux/ppc64le
+          # - linux/s390x
+      target: ${TARGET:-dist}
+    volumes:
+      - .:/local
+    command: ["help"]

docker/entrypoint.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+function usage() {
+  echo "Usage: docker run --rm -v \`pwd\`:/local ohm:lastest <cmd>"
+  echo ""
+  echo "  where cmd is compile, generateBundles or shell"
+  echo ""
+  echo "  compile usage: [(--debug|-d)] [(--grammarName|-g) <name>] [(--output|-o) <file>] <ohm-grammar-file>"
+  echo ""
+  echo "  generateBundles - currently not working"
+  echo ""
+  echo "  shell: drop into a bash shell in the container, useful for debug the docker build"
+  echo ""
+}
+
+if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+  usage
+  exit 0
+fi
+
+case "$1" in
+  compile)
+    shift
+    mkdir -p /local
+    cd /local
+    node \
+      --disable-warning=ExperimentalWarning \
+      /ohm/packages/compiler/dist/src/cli.js "$@"
+    ;;
+  generateBundles)
+    set -x
+    shift
+    mkdir -p /local
+    cd /local
+    node /ohm/packages/cli/src/cli.js generateBundles "$@"
+    ;;
+  shell)
+    /bin/bash
+    ;;
+  *)
+    echo "Unknown command: $1"
+    usage
+    exit 1
+    ;;
+esac

docker/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - 'packages/*'
+linkWorkspacePackages: true
+# injectWorkspacePackages: true
+minimumReleaseAge: 1440

package.json

@@ -1,6 +1,5 @@
 {
   "private": true,
-  "packageManager": "pnpm@10.10.0",
   "scripts": {
     "api-report": "pnpm --filter ohm-js --filter @ohm-js/compiler api-report",
     "build": "pnpm -r build",