devthefuture/dockerfile-x: Dockerfile factorization superset

dockerfile-x empowers developers with an extended syntax that allow modular factorization with ease.

Getting Started:

To enable dockerfile-x custom syntax, you can use native docker buildkit frontend feature by adding syntax comment to the beginning of your Dockerfile:

# syntax = devthefuture/dockerfile-x

FROM ./base/dockerfile

COPY --from=./build/dockerfile#build-stage /app /app

INCLUDE ./other/dockerfile

That's it!

then you can run buildkit as usual:

docker build .

note that you can also use docker compose or other tools that rely on docker buildkit.

this will compile the final Dockerfile using devthefuture/dockerfile-x docker image, just before running the build

Requirements

We recommend using Docker 20.10 or later.

However, if you're working with Docker versions as old as 18.09, you can still enable BuildKit. To do so, you'll need to set the following environment variables: DOCKER_BUILDKIT=1 and COMPOSE_DOCKER_CLI_BUILD=1.

Features:

INCLUDE: Incorporate content as is from other Dockerfiles or snippets.
INCLUDE_ARGS: Converts a .env file into Dockerfile ARG instructions.
INCLUDE_ENVS: Converts a .env file into Dockerfile ENV instructions.
INCLUDE_LABELS: Converts a .env file into Dockerfile LABEL instructions.
FROM:
- FROM with Relative Paths: Use other Dockerfiles as a base using relative paths.
- FROM with Stages: Reference specific stages from other Dockerfiles.
- FROM with Re-Alias: Rename specific stages from other Dockerfiles.
COPY --from:
- COPY/ADD from Another Dockerfile: Transfer files from another Dockerfile.
- COPY/ADD with Stages: Specify a stage when copying files from another Dockerfile.
Remote sources: pull included Dockerfiles from HTTP(S), Git, or OCI registries.
Recursion guard: default depth limit and cycle detection across local and remote includes.

Behavior

`FROM` File Syntax:

For a file to be recognized as an included Dockerfile, the FROM| or --from parameters must begin with either a . (examples: ./another/dockerfile or ../parent-dir/my.dockerfile) or /. Any Dockerfile imported via this custom FROM syntax will be treated according to the rules specified below.

Scoping:

Dockerfiles included via the INCLUDE instruction are integrated as they are, without any modifications.
Dockerfiles brought in through the FROM instruction or --from parameters undergo scoping to prevent conflicts with other Dockerfiles. Specifically:
- All stages are renamed based on the scope.
- This scoping is transparent to users: one can re-alias imported stages (or the final stage of the imported Dockerfile if no stage is explicitly mentioned) and utilize them as needed.
All processing and the features described are recursive. Only the final stages of the root Dockerfile are made visible to the user, suitable for use with the --target parameter during a Docker build.
A Dockerfile can be imported many times using FROM instruction or --from parameters, at same or different stages, the imported stages will be deduplicated automatically.
The paths resolutions for imported Dockerfiles from the root Dockerfile are relative to the docker build context, not the root Dockerfile itself. This is due to a limitation in BuildKit and this is consistent with other instructions that are also relative the context. The imported Dockerfiles must be in the build context, but can be safely ignored from .dockerignore. Symlinking does not help in this case.
However, the paths resolutions for imported Dockerfiles from the imported Dockerfiles are relative to the imported Dockerfile itself.

Dockerfile Extension:

If you're importing a Dockerfile with the .dockerfile extension, you don't need to specify the extension; it will be detected automatically.

Examples:

Basic INCLUDE

INCLUDE ./common-instructions.dockerfile

FROM debian:latest

CMD ["bash"]

Using stages from another Dockerfile

FROM ./base/dockerfile#dev AS development

COPY . /app

FROM ./base/dockerfile#prod AS production

COPY --from=development /app /app
CMD ["start-app"]

Re-aliasing a stage

FROM ./complex-setup/dockerfile#old-stage-name AS new-name

COPY ./configs /configs

Features documentation:

INCLUDE

Easily include content from another Dockerfile or snippet, ensuring straightforward reuse of Dockerfile segments across projects.

# Include another Dockerfile's content
INCLUDE ./path/to/another/dockerfile

INCLUDE_ARGS

Converts key-value pairs from a .env file into Dockerfile ARG instructions. Use this to expose build-time variables without hardcoding them into the Dockerfile.

# custom-args.env
NODE_VERSION=20.11.1
PNPM_VERSION=9.1.0

# Include key-value pairs from file
INCLUDE_ARGS ./path/to/custom-args.env

This expands to:

ARG NODE_VERSION="20.11.1"
ARG PNPM_VERSION="9.1.0"

Note: Values can be overridden at build time with --build-arg if desired.

INCLUDE_ENVS

Converts key-value pairs from a .env file into Dockerfile ENV instructions. Ideal for runtime configuration baked into the image.

# custom-envvars.env
NODE_ENV=production
APP_PORT=8080

# Include key-value pairs from file
INCLUDE_ENVS ./path/to/custom-envvars.env

This expands to:

ENV NODE_ENV="production"
ENV APP_PORT="8080"

INCLUDE_LABELS

Converts key-value pairs from a .env file into Dockerfile LABEL instructions. Useful for image metadata (e.g., authorship, version, VCS refs).

# custom-labels.env
org.opencontainers.image.title=myapp
org.opencontainers.image.version=1.2.3
org.opencontainers.image.revision=abc1234

# Include key-value pairs from file
INCLUDE_LABELS ./path/to/custom-labels.env

This expands to:

LABEL org.opencontainers.image.title="myapp" 
LABEL org.opencontainers.image.version="1.2.3" 
LABEL org.opencontainers.image.revision="abc1234"

FROM

FROM with Relative Paths

Instead of using image names from DockerHub or another registry, use relative paths to refer to other Dockerfiles directly.

# Use another Dockerfile as a base
FROM ./path/to/another/dockerfile

FROM with Stages

Or use a specific stage from another Dockerfile:

# Use a specific stage from another Dockerfile
FROM ./path/to/another/dockerfile#stage-name

FROM with Re-Alias

Re-alias a specific stage from another Dockerfile to a new name, providing flexibility in naming.

# Re-alias a stage from another Dockerfile
FROM ./path/to/another/dockerfile#original-stage-name AS new-stage-name

COPY --from

COPY/ADD from Another Dockerfile

Copy or add files directly from another Dockerfile, streamlining the process of transferring files between build stages.

# Copy files from another Dockerfile
COPY --from=/path/to/another/dockerfile source-path destination-path

# Add files from another Dockerfile
ADD --from=/path/to/another/dockerfile source-path destination-path

COPY/ADD with Stages

Or specify a stage from which to copy or add:

# Copy files from a specific stage of another Dockerfile
COPY --from=/path/to/another/dockerfile#stage-name source-path destination-path

Remote sources

Any reference (in INCLUDE, INCLUDE_ARGS|ENVS|LABELS, FROM, COPY --from=, ADD --from=) can target a remote location. Three schemes are supported:

HTTP(S)

INCLUDE https://example.com/snippets/setup.dockerfile
FROM https://example.com/base/alpine.dockerfile AS base

The fetcher caches responses in ~/.dockerfile-x/cache using ETag / Last-Modified and falls back to the cached copy on network errors. Override the cache directory with DOCKERFILEX_CACHE_DIR.

Git (sparse fetch — no full clone)

INCLUDE git+https://github.com/foo/bar.git#main:dockerfiles/base.dockerfile
FROM git+ssh://git@github.com/foo/bar.git#v1.2.3:base.dockerfile AS base

Format: git+<git-url>#<ref>:<path>. <ref> is a branch, tag, or full commit SHA (40-hex SHA-1 or 64-hex SHA-256):

Branch / tag: git clone --depth 1 --filter=blob:none --no-checkout --single-branch --branch <ref>. The fetcher then resolves the moving ref's current oid via git ls-remote and uses that as the cycle-detection key — so a moving main still cycle-checks deterministically.
Commit SHA: git init + git fetch --depth 1 --filter=blob:none origin <sha> (protocol v2). Requires the upstream server to allow fetch-by-oid. Works out of the box with GitHub, GitLab (.com and self-hosted), Gitea / Forgejo, Bitbucket Cloud, and file:// bare repos. Plain git http-backend / older self-hosted servers may need uploadpack.allowReachableSHA1InWant=true (or allowAnySHA1InWant) on the server.

Supply-chain pinning. Pinning to a commit SHA (or an OCI digest, see below) is the strongest defense against a compromised or rewritten upstream: once the build resolves the artifact, an attacker who force-pushes the same branch (or republishes the same tag) cannot change what your build sees. Pin in production builds; use moving refs only for development.

Both forms produce the same on-cache layout; git sparse-checkout set <dir> materializes only the requested file's directory. Authentication uses your standard Git mechanisms (GIT_ASKPASS, ~/.netrc, credential helpers). For BuildKit usage, pass credentials via a build secret:

docker buildx build --secret id=git-credentials,src=$HOME/.git-credentials .

The cache directory is ~/.dockerfile-x/git-cache (override via DOCKERFILEX_GIT_CACHE_DIR).

OCI artifacts

INCLUDE oci://ghcr.io/foo/bar:1.0#dockerfiles/common.dockerfile
FROM oci://registry.example.com/base/alpine:3.19#Dockerfile AS base

Format: oci://<registry>/<repo>(:<tag>|@<digest>)#<path>.

Supply-chain pinning. Use the @<algo>:<hex> digest form (oci://reg/repo@sha256:abc…#path) in production builds — same rationale as a git commit SHA: an attacker who republishes the tag cannot change what your build sees, and dockerfile-x skips the manifest-fetch round-trip when the digest is already known. Tag form (:<tag>) is convenient for development; the resolved digest still becomes the cycle-detection key, but a future build pulls whatever the tag now points to.

Pulled via oras using ~/.docker/config.json for authentication, including credential helpers (docker-credential-ecr-login is bundled in the runtime image; docker-credential-gcr, docker-credential-acr-env, etc. can be added in a derived image). Resolution cascade for the auth file:

/run/secrets/docker-config (BuildKit build secret)
$DOCKER_CONFIG/config.json
$HOME/.docker/config.json

For BuildKit usage, mount your Docker config:

docker buildx build --secret id=docker-config,src=$HOME/.docker/config.json .

The cache directory is ~/.dockerfile-x/oci-cache (override via DOCKERFILEX_OCI_CACHE_DIR). Localhost registries (127.0.0.1, localhost) are pulled with --plain-http; for any other host the env var DOCKERFILEX_ORAS_PLAIN_HTTP=true forces it.

Recursive resolution

A remote-included Dockerfile may itself contain INCLUDE, FROM, or COPY --from directives. Relative references resolve against the parent's location:

Parent scheme	`INCLUDE ./foo.dockerfile` resolves to
HTTP(S)	`new URL("./foo.dockerfile", parentUrl)`
Git	same `repo#ref`, sibling path
OCI	same artifact, sibling path
Local	sibling path on disk (existing behavior)

A nested reference may also use a different scheme — git+https://…#main:foo.dockerfile inside an HTTP-fetched Dockerfile is fine; resolution is delegated to resolveSource.

Recursion guard

dockerfile-x enforces two safeguards across local and remote includes:

Maximum depth — default 32. Exceeding it produces a JSON error on stdout and exit code 2: {"error":"include-depth-exceeded","depth":N,"max":32,"chain":[...]}. Override with --max-include-depth <n> or env DOCKERFILEX_MAX_INCLUDE_DEPTH.
Cycle detection — if any Dockerfile re-references itself transitively, you get {"error":"include-cycle","chain":[...]} and exit 2. The cycle key for Git/OCI is the resolved commit oid / artifact digest, so a moving main or :latest tag still detects loops correctly.

Error codes

When the CLI encounters a structured error, it writes a single-line JSON object to stdout and exits with code 2. The Go BuildKit frontend distinguishes the codes below; only missing-file triggers an LLB-context retry — every other code surfaces directly as a build error.

Code	Trigger	Extra fields
`missing-file`	Local include path not found in the build context	`filename`
`remote-file-not-found`	HTTP 404, git path missing in repo, or oci path missing in artifact	`ref`
`include-cycle`	A reference re-enters its own include chain	`chain`
`include-depth-exceeded`	More than `--max-include-depth` nested includes	`depth`, `max`, `chain`
`path-traversal`	A `..` segment, absolute path, or symlink resolves outside its source	`ref`
`remote-fetch-failed`	HTTP error other than 404, oversize body, refused redirect (HTTPS→HTTP downgrade, non-`http(s)` scheme, or cross-host redirect to a private IP not on `DOCKERFILEX_REDIRECT_ALLOWLIST`)	`url`, `originalUrl?`, `message`

Environment variables

Variable	Default	Purpose
`DOCKERFILEX_MAX_INCLUDE_DEPTH`	`32`	Maximum nested include depth (also via `--max-include-depth`).
`DOCKERFILEX_HTTP_TIMEOUT_MS`	`30000`	HTTP request timeout in milliseconds.
`DOCKERFILEX_MAX_HTTP_BYTES`	`1048576`	Maximum HTTP response body size in bytes (1 MiB). Caps memory use against hostile servers.
`DOCKERFILEX_MAX_REDIRECTS`	`5`	Maximum HTTP redirects followed. HTTPS→HTTP downgrades and non-`http(s)` schemes are always refused.
`DOCKERFILEX_REDIRECT_ALLOWLIST`	unset	Comma-separated list permitting cross-host redirects to private IPs (loopback, RFC1918, link-local, ULA — denied by default to mitigate SSRF). Entries can be exact IPs (`192.168.1.10`), IPv4 CIDRs (`10.0.0.0/8`), exact hostnames (`internal.corp.local`), or suffix wildcards (`*.corp.local`).
`DOCKERFILEX_SUBPROCESS_TIMEOUT_MS`	`300000`	Timeout for `git` / `oras` invocations (5 min).
`DOCKERFILEX_CACHE_DIR`	`~/.dockerfile-x/cache`	HTTP response cache.
`DOCKERFILEX_GIT_CACHE_DIR`	`~/.dockerfile-x/git-cache`	Git sparse-clone cache.
`DOCKERFILEX_OCI_CACHE_DIR`	`~/.dockerfile-x/oci-cache`	OCI artifact cache.
`DOCKERFILEX_ORAS_PLAIN_HTTP`	unset	Set to `true` to force plaintext HTTP for non-localhost OCI registries. Use with care — disables TLS for all registry traffic.
`DOCKERFILEX_ORAS_BIN`	`oras`	Path to the `oras` binary.
`DOCKERFILEX_TMPDIR`	`os.tmpdir()`	Directory for the stdin temp file when reading from `-`.

Network access

The runtime image ships with network access enabled (the upstream BuildKit network.none capability is dropped) so that the frontend can fetch HTTP/Git/OCI sources. A malicious Dockerfile could exfiltrate data via the references it declares — audit Dockerfiles you do not trust before building.

Addressing Dockerfile Evolution Concerns

Understanding concerns regarding feature availability with alternative frontends:

Some might worry that alternative frontends would lack the ability to layer on top of the official docker/dockerfile, potentially missing out on its additional features. Let's address this concern for dockerfile-x.

How `dockerfile-x` Operates:

Node.js Compilation: The Node.js component compiles custom Dockerfile syntax into the standard Dockerfile format in a superset manner.
BuildKit Frontend Service: This service then translates the standard Dockerfile to LLB. This step uses minimal custom code, predominantly relying on official BuildKit packages.

Addressing Future Updates to `docker/dockerfile`:

Though updates to docker/dockerfile aren't frequent, here's how we'd accommodate them:

Upgrade the Go Package: The Go part of dockerfile-x is lean in terms of custom code. Thus, maintaining it and integrating any updates from docker/dockerfile would be straightforward.
Direct Compilation with Node.js: Instead of using the custom syntax frontend, users can compile the Dockerfile-X directly to a standard Dockerfile using only the Node.js component. This standalone CLI tool can be used via the command npx dockerfile-x (further details available with --help). Any new additions to docker/dockerfile, like novel keywords, would be inherently supported without needing any modifications to this library.

In essence, one could think of dockerfile-x as a dedicated template engine specially crafted for Dockerfiles.

Why

With the growing complexity of Docker setups, this tool ensures your Dockerfiles remain clean, maintainable, and modular.

Contributing:

We welcome contributions! If you encounter a bug or have a feature suggestion, please open an issue. To contribute code, simply fork the repository and submit a pull request.

This repository is mirrored on both GitHub and Codeberg. Contributions can be made on either platform, as the repositories are synchronized bidirectionally.

Codeberg: https://codeberg.org/devthefuture/dockerfile-x
GitHub: https://github.com/devthefuture-org/dockerfile-x

For more information:

Development

Enable debugging

/etc/docker/daemon.json

{
    "experimental": true,
    "debug": true
}

sudo systemctl restart docker

then observe the logs

journalctl -u docker.service -f

TODO NEXT

features:

allow customization hook/plugins autoloading .dockerfile-x.js or .dockerfile-x/index.js (eg: integration of yarn workspaces topographically)

ci .gitea (for codeberg):

release
publish to npm
build and push images to docker registry and codeberg registry

Name		Name	Last commit message	Last commit date
Latest commit History 98 Commits
.github/workflows		.github/workflows
.vscode		.vscode
.yarn		.yarn
bin		bin
pkg		pkg
src		src
test		test
vendor		vendor
.dockerignore		.dockerignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.mocharc.js		.mocharc.js
.npmignore		.npmignore
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
index.js		index.js
main.go		main.go
package.json		package.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

devthefuture/dockerfile-x: Dockerfile factorization superset

Getting Started:

Requirements

Features:

Behavior

FROM File Syntax:

Scoping:

Dockerfile Extension:

Examples:

Features documentation:

INCLUDE

INCLUDE_ARGS

INCLUDE_ENVS

INCLUDE_LABELS

FROM

FROM with Relative Paths

FROM with Stages

FROM with Re-Alias

COPY --from

COPY/ADD from Another Dockerfile

COPY/ADD with Stages

Remote sources

HTTP(S)

Git (sparse fetch — no full clone)

OCI artifacts

Recursive resolution

Recursion guard

Error codes

Environment variables

Network access

Addressing Dockerfile Evolution Concerns

How dockerfile-x Operates:

Addressing Future Updates to docker/dockerfile:

Why

Related

Contributing:

Development

Enable debugging

TODO NEXT

features:

ci .gitea (for codeberg):

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`FROM` File Syntax:

How `dockerfile-x` Operates:

Addressing Future Updates to `docker/dockerfile`:

Packages