How to Run the PDML Companion in a Docker Container?

This document explains how to run the PDML Companion in a Docker container on macOS, Unix/Linux or Windows.

Two steps are involved:

create a container
run the container

Creating a Docker Container

To create a Docker container for the PDML Companion (PDMLC) command line tool, proceed as follows:

If not done already, install Docker (and ensure that your OS complies with the Docker system requirements).
Open a terminal in a directory of your choice, create a working directory (e.g. pdml-docker), and move into that directory, e.g.:
```
mkdir pdml-docker
cd pdml-docker
```

Create file Dockerfile and copy-paste the following content:

File Dockerfile

FROM openjdk:17-alpine

ARG PDML_VERSION=0.78.0

WORKDIR /app

# Install PDMLC
RUN apk update && apk add --no-cache curl
RUN curl -O https://github.com/pdml-lang/full-pdml-impl/releases/download/v${PDML_VERSION}/pdmlc-java-app-${PDML_VERSION}.tar
RUN tar -xf pdmlc-java-app-${PDML_VERSION}.tar

ENV PATH="/app/pdmlc-java-app-${PDML_VERSION}/bin:${PATH}"

WORKDIR /

CMD ["/bin/sh"]

Build a Docker image by typing:
```
docker build -t pdmlc .
```
(Note the required dot at the end of the command)

Running the Container

To run PDMLC in a Docker container type:

docker run -it pdmlc

You can now enter PDMLC commands in the terminal session of the Docker container.

For example, to get a list of available PDMLC commands, type:

pdmlc help

Useful Options

Access to Host Files

If you need read/write access to a directory of your host OS, use the -v option of the Docker run command.

For example, suppose that you are using Windows, and you want to access files in directory C:\temp\test\ from within your Docker container. In that case, you can use the -v option as follows:

docker run -it -v C:\temp\test:/docs pdmlc

This maps C:\temp\test\ to directory /docs in your container, so that you can read from and write to C:\temp\test\ via /docs.

For example, the following PDMLC command (executed in your container), reads file C:\temp\test\config.pdml and creates file C:\temp\test\tree_view.html (which you can open in your standard Windows browser):

pdmlc p2h /docs/config.pdml /docs/tree_view.html

Container User

Note

This section applies only to Unix-like host systems — it doesn't apply to Windows.

By default, Docker containers run as the root user inside the container, which can cause permission and security issues.

To specify the user under which the container runs, you can use the -u option of the Docker run command. For example, to specify a user with UID 1000 and GID 1000:

docker run -it -u 1000:1000

Specifying -u $(id -u):$(id -g) ensures the container process runs as the current user (with the same UID and GID as the host user) rather than as root:

docker run -it -u $(id -u):$(id -g)

The expression $(id -u):$(id -g) is a shell substitution that uses the Unix id command to dynamically fetch the user ID (UID) and group ID (GID) of the current user.