Caution

THIS LIBRARY IS CURRENTLY PRE-RELEASE

pkl-docker is currently major version v0, and breaking changes will happen between versions.

Please read the section Roadmap below to learn more.

pkl-docker

This repo implements Docker config files such as Dockerfiles (and, in the future, Docker Compose) in the Pkl configuration language.

pkl.dockerfile

📝 Dockelfile 101

To write a Dockelfile, simply amend the Dockelfile module.

For example, create a file ex1.Dockerfile.pkl:

amends "package://github.com/jjmaestro/pkl-docker/releases/download/<VERSION>/pkl.dockerfile@<VERSION>/Dockelfile.pkl"

dockerfile = new {
  instructions = new Listing {
    module.Arg("CODE_VERSION", "latest")
    new From {
      image = new Image { name = "hello-world" version = "$CODE_VERSION" alias = "foo" }
      platform = "$BUILDPLATFORM"
    }
  }
}

Make sure to substitute <VERSION> with one of the released versions and then, materialize the Dockerfile with:

$ pkl eval ex1.Dockerfile.pkl > Dockerfile

and you'll get:

# syntax=docker/dockerfile:1


ARG CODE_VERSION=latest
FROM --platform=$BUILDPLATFORM hello-world:$CODE_VERSION AS foo

Finally, to make the amend much more readable and make development easier, create a PklProject file such as:

amends "pkl:Project"

dependencies {
  ["dockerfile"] {
    uri = "package://github.com/jjmaestro/pkl-docker/releases/download/<VERSION>/pkl.dockerfile@<VERSION>"
  }
}

Then, run pkl project resolve and you'll be able to use a nicely readable amend:

amends "@dockerfile/Dockelfile.pkl"
(...)

🧩 Requirements

To use these libraries, you just need to install Pkl.

Note

You need to use at least Pkl v0.26 due to a bug in the scoping of typealias in v0.25

🧪 Development

If you want to help with further development of this library, please install:

• GNU make + bash: to run the tests
• Python: to generate Dockerfiles from the JSON generated from the Pkl test examples
• Docker: to fully validate & test the Dockerfiles generated from the Pkl test examples

With these installed you should be able to run make at the root of the repository to run all tests (all unit tests and Docker validation tests of the test/examples):

pkl-docker $ make
Pkl 0.26.0 (macOS 13.6.6, native)


Thu 10 Jun 2024 22:50:33 BST

module pkl.dockerfile.tests.Dockelfile (file://tests/Dockelfile.pkl, line 1)
  VariableName ✅
  Variable ✅
  Platform ✅
  ImageTag ✅
  Digest ✅
  ImageDigest ✅
  ImageTagPinned ✅
  HereDocDelim ✅
  HereDoc ✅
  UnixUserGroup ✅
  OctalDigit ✅
  UnixPerm ✅
  UnixSignal ✅
  Port ✅
  dfmt ✅
  HealthcheckDuration ✅
  HardcodedDirective ✅
  Directive ✅
  Arg ✅
  Image ✅
  From ✅
  CommandShell ✅
  ShellDelim ✅
  CommandShellGrouped ✅
  CommandExec ✅
  Command ✅
  Shell ✅
  Cmd ✅
  Healthcheck ✅
  Add ✅
  Copy ✅
  Run ✅
  KV ✅
  KVs ✅
  Label ✅
  Env ✅
  Expose ✅
  Entrypoint ✅
  Volume ✅
  User ✅
  Workdir ✅
  OnBuild ✅
  StopSignal ✅
  ex1.Dockerfile ✅
  ex2.Dockerfile ✅
module pkl.dockerfile.tests.stringify (file://tests/stringify.pkl, line 1)
  listify ✅
  listifyOrNull ✅
  Stringy ✅
  Stringies ✅
  LStringies ✅
  sPrefix ✅
  sDelim ✅
  sKEQVs ✅

>> Generating dockerfiles from the examples...
>>>> ex1.Dockerfile
>>>> ex2.Dockerfile

>> Validating Dockerfile syntax...
>>>> ex1.Dockerfile
>>>> ex2.Dockerfile
>>>> All generated examples validate OK

Note that this will run docker build on the test examples, so these must be fully working Dockerfiles. Also, this last step can take a bit longer, so if you have a powerful computer you can always run make -j N.

I've tried to keep the dependencies to a minimum. All these tools are usually already installed in most computers nowadays (e.g. MacOS or most Linux distros). Also, it seems that MacOS only ships the last GPLv2 versions of these GNU tools (make v.3.81 circa Apr 2006 and bash 3.2.57 circa Nov 2014!) so I've made sure that everything works with these ancient versions. This is a bummer, as make 3.82 had e.g. .ONESHELL and other good improvements 😭 but really wanted to lower the "barrier of entry" for development. Ideally, it should be just one git clone away.

If you want to improve the development experience a bit, you should also install fswatch so that you can run make dev. This will run make test every time one of the source .pkl files changes, so that you can edit the source on one window and have all tests automatically run on another.

🚧 Roadmap

This library is currently in pre-release: it is probably usable and productive in its current state, and it should cover all of the Dockerfile functionality up to today (currently docker/dockerfile:1.7-labs).

However:

• It still needs further testing and validation with e.g. real-life Dockerfile examples
• There might still be big refactors that could change syntax and break backwards compatibility. That is, this library is still not yet API-stable.

So... CAVEAT EMPTOR!☝️