{"id":14156135,"url":"https://github.com/devthefuture-org/dockerfile-x","last_synced_at":"2026-01-23T05:29:31.321Z","repository":{"id":193231391,"uuid":"688365620","full_name":"devthefuture-org/dockerfile-x","owner":"devthefuture-org","description":"Dockerfile factorization superset","archived":false,"fork":false,"pushed_at":"2025-08-27T17:36:41.000Z","size":27723,"stargazers_count":49,"open_issues_count":5,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-28T02:18:55.441Z","etag":null,"topics":["buildkit","dockerfile","factorization","include","template"],"latest_commit_sha":null,"homepage":"https://codeberg.org/devthefuture/dockerfile-x/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devthefuture-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-07T07:45:18.000Z","updated_at":"2025-08-27T17:36:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"ffaf597b-1f42-46fb-80e5-27c93017e73a","html_url":"https://github.com/devthefuture-org/dockerfile-x","commit_stats":null,"previous_names":["devthefuture-org/dockerfile-x"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/devthefuture-org/dockerfile-x","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devthefuture-org%2Fdockerfile-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devthefuture-org%2Fdockerfile-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devthefuture-org%2Fdockerfile-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devthefuture-org%2Fdockerfile-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devthefuture-org","download_url":"https://codeload.github.com/devthefuture-org/dockerfile-x/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devthefuture-org%2Fdockerfile-x/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28680694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T04:33:33.518Z","status":"ssl_error","status_checked_at":"2026-01-23T04:33:30.433Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildkit","dockerfile","factorization","include","template"],"created_at":"2024-08-17T08:05:14.497Z","updated_at":"2026-01-23T05:29:31.315Z","avatar_url":"https://github.com/devthefuture-org.png","language":"JavaScript","funding_links":[],"categories":["others","JavaScript"],"sub_categories":[],"readme":"# devthefuture/dockerfile-x: Dockerfile factorization superset\n\n`dockerfile-x` empowers developers with an extended syntax that allow modular factorization with ease.\n\n## Getting Started:\n\nTo enable `dockerfile-x` custom syntax, you can use native docker buildkit frontend feature by adding syntax comment to the beginning of your Dockerfile:\n\n```Dockerfile\n# syntax = devthefuture/dockerfile-x\n\nFROM ./base/dockerfile\n\nCOPY --from=./build/dockerfile#build-stage /app /app\n\nINCLUDE ./other/dockerfile\n```\n\nThat's it!\n\nthen you can run buildkit as usual:\n\n```sh\ndocker build .\n```\n\nnote that you can also use `docker compose` or other tools that rely on docker buildkit.\n\nthis will compile the final Dockerfile using [devthefuture/dockerfile-x](https://hub.docker.com/r/devthefuture/dockerfile-x) docker image, just before running the build\n\n### Requirements\n\nWe recommend using Docker 20.10 or later.\n\nHowever, 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`.\n\n## Features:\n- [INCLUDE](#include): Incorporate content as is from other Dockerfiles or snippets.\n- [INCLUDE_ARGS](#include_args): Converts a `.env` file into Dockerfile `ARG` instructions.\n- [INCLUDE_ENVS](#include_envs): Converts a `.env` file into Dockerfile `ENV` instructions.\n- [INCLUDE_LABELS](#include_labels): Converts a `.env` file into Dockerfile `LABEL` instructions.\n- [FROM](#from):\n  - [FROM with Relative Paths](#from-with-relative-paths): Use other Dockerfiles as a base using relative paths.\n  - [FROM with Stages](#from-with-stages): Reference specific stages from other Dockerfiles.\n  - [FROM with Re-Alias](#from-with-re-alias): Rename specific stages from other Dockerfiles.\n- [COPY --from](#copy-from):\n  - [COPY/ADD from Another Dockerfile](#copy-add-from-another-dockerfile): Transfer files from another Dockerfile.\n  - [COPY/ADD with Stages](#copy-add-with-stages): Specify a stage when copying files from another Dockerfile.\n\n## Behavior\n\n### `FROM` File Syntax:\n\nFor 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.\n\n### Scoping:\n\n- Dockerfiles included via the `INCLUDE` instruction are integrated as they are, without any modifications.\n \n- Dockerfiles brought in through the `FROM` instruction or `--from` parameters undergo scoping to prevent conflicts with other Dockerfiles. Specifically:\n  - All stages are renamed based on the scope.\n  - 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.\n\n- 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.\n\n- 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.\n\n- 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.\n- However, the paths resolutions **for imported Dockerfiles from the imported Dockerfiles** are relative to the imported Dockerfile itself.\n\n### Dockerfile Extension:\n\n- If you're importing a Dockerfile with the `.dockerfile` extension, you don't need to specify the extension; it will be detected automatically.\n\n\n## Examples:\n\nBasic INCLUDE\n\n```Dockerfile\nINCLUDE ./common-instructions.dockerfile\n\nFROM debian:latest\n\nCMD [\"bash\"]\n```\n\nUsing stages from another Dockerfile\n\n```Dockerfile\nFROM ./base/dockerfile#dev AS development\n\nCOPY . /app\n\nFROM ./base/dockerfile#prod AS production\n\nCOPY --from=development /app /app\nCMD [\"start-app\"]\n```\n\nRe-aliasing a stage\n\n```Dockerfile\nFROM ./complex-setup/dockerfile#old-stage-name AS new-name\n\nCOPY ./configs /configs\n```\n\n## Features documentation:\n\n### INCLUDE\n\nEasily include content from another Dockerfile or snippet, ensuring straightforward reuse of Dockerfile segments across projects.\n\n```Dockerfile\n# Include another Dockerfile's content\nINCLUDE ./path/to/another/dockerfile\n```\n\n### INCLUDE_ARGS\n\nConverts key-value pairs from a `.env` file into Dockerfile `ARG` instructions.\nUse this to expose build-time variables without hardcoding them into the Dockerfile.\n\n```text\n# custom-args.env\nNODE_VERSION=20.11.1\nPNPM_VERSION=9.1.0\n```\n\n```Dockerfile\n# Include key-value pairs from file\nINCLUDE_ARGS ./path/to/custom-args.env\n```\n\nThis expands to:\n```Dockerfile\nARG NODE_VERSION=\"20.11.1\"\nARG PNPM_VERSION=\"9.1.0\"\n```\n\n**Note:** Values can be overridden at build time with `--build-arg` if desired.\n\n### INCLUDE_ENVS\n\nConverts key-value pairs from a `.env` file into Dockerfile `ENV` instructions.\nIdeal for runtime configuration baked into the image.\n\n```text\n# custom-envvars.env\nNODE_ENV=production\nAPP_PORT=8080\n```\n\n```Dockerfile\n# Include key-value pairs from file\nINCLUDE_ENVS ./path/to/custom-envvars.env\n```\n\nThis expands to:\n```Dockerfile\nENV NODE_ENV=\"production\"\nENV APP_PORT=\"8080\"\n```\n\n### INCLUDE_LABELS\nConverts key-value pairs from a `.env` file into Dockerfile `LABEL` instructions.\nUseful for image metadata (e.g., authorship, version, VCS refs).\n\n```text\n# custom-labels.env\norg.opencontainers.image.title=myapp\norg.opencontainers.image.version=1.2.3\norg.opencontainers.image.revision=abc1234\n```\n\n```Dockerfile\n# Include key-value pairs from file\nINCLUDE_LABELS ./path/to/custom-labels.env\n```\n\nThis expands to:\n```Dockerfile\nLABEL org.opencontainers.image.title=\"myapp\" \nLABEL org.opencontainers.image.version=\"1.2.3\" \nLABEL org.opencontainers.image.revision=\"abc1234\"\n```\n\n### FROM\n\n#### FROM with Relative Paths\n\nInstead of using image names from DockerHub or another registry, use relative paths to refer to other Dockerfiles directly.\n\n```Dockerfile\n# Use another Dockerfile as a base\nFROM ./path/to/another/dockerfile\n```\n\n#### FROM with Stages\n\nOr use a specific stage from another Dockerfile:\n\n```Dockerfile\n# Use a specific stage from another Dockerfile\nFROM ./path/to/another/dockerfile#stage-name\n\n```\n\n#### FROM with Re-Alias\n\nRe-alias a specific stage from another Dockerfile to a new name, providing flexibility in naming.\n\n```Dockerfile\n# Re-alias a stage from another Dockerfile\nFROM ./path/to/another/dockerfile#original-stage-name AS new-stage-name\n```\n\n### COPY --from\n\n#### COPY/ADD from Another Dockerfile\n\nCopy or add files directly from another Dockerfile, streamlining the process of transferring files between build stages.\n\n```Dockerfile\n# Copy files from another Dockerfile\nCOPY --from=/path/to/another/dockerfile source-path destination-path\n\n# Add files from another Dockerfile\nADD --from=/path/to/another/dockerfile source-path destination-path\n```\n\n#### COPY/ADD with Stages\n\nOr specify a stage from which to copy or add:\n\n```Dockerfile\n# Copy files from a specific stage of another Dockerfile\nCOPY --from=/path/to/another/dockerfile#stage-name source-path destination-path\n```\n\n## Addressing Dockerfile Evolution Concerns\n\nUnderstanding concerns regarding feature availability with alternative frontends:\n\nSome 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`.\n\n### How `dockerfile-x` Operates:\n1. **Node.js Compilation**: The Node.js component compiles custom Dockerfile syntax into the standard Dockerfile format in a superset manner.\n2. **BuildKit Frontend Service**: This service then translates the standard Dockerfile to LLB. This step uses minimal custom code, predominantly relying on official BuildKit packages.\n\n### Addressing Future Updates to `docker/dockerfile`:\nThough updates to `docker/dockerfile` aren't frequent, here's how we'd accommodate them:\n\n1. **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.\n2. **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.\n\nIn essence, one could think of `dockerfile-x` as a dedicated template engine specially crafted for Dockerfiles.\n\n\n## Why\n\nWith the growing complexity of Docker setups, this tool ensures your Dockerfiles remain clean, maintainable, and modular.\n\n### Related\n\n- https://github.com/moby/moby/issues/735\n- https://stackoverflow.com/questions/36362233/can-a-dockerfile-extend-another-one\n\n## Contributing:\n\nWe 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.\n\nThis repository is mirrored on both GitHub and Codeberg. Contributions can be made on either platform, as the repositories are synchronized bidirectionally. \n- Codeberg: [https://codeberg.org/devthefuture/dockerfile-x](https://codeberg.org/devthefuture/dockerfile-x)\n- GitHub: [https://github.com/devthefuture-org/dockerfile-x](https://github.com/devthefuture-org/dockerfile-x)\n\nFor more information:\n- [Why mirror to Codeberg?](https://codeberg.org/Recommendations/Mirror_to_Codeberg#why-should-we-mirror-to-codeberg)\n- [GitHub to Codeberg mirroring tutorial](https://codeberg.org/Recommendations/Mirror_to_Codeberg#github-codeberg-mirroring-tutorial)\n\n\n### Development\n\n#### Enable debugging\n\n`/etc/docker/daemon.json`\n\n```json\n{\n    \"experimental\": true,\n    \"debug\": true\n}\n```\n\n```sh\nsudo systemctl restart docker\n```\n\nthen observe the logs\n```sh\njournalctl -u docker.service -f\n```\n\n## TODO NEXT\n\n### features:\n- remote url feature with recursive remote resolution\n- allow customization hook/plugins autoloading .dockerfile-x.js or .dockerfile-x/index.js (eg: integration of yarn workspaces topographically)\n\n### ci .gitea (for codeberg):\n- release\n- publish to npm\n- build and push images to docker registry and codeberg registry","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevthefuture-org%2Fdockerfile-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevthefuture-org%2Fdockerfile-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevthefuture-org%2Fdockerfile-x/lists"}