dockerfile-plus/README.md

# Dockerfile+

This project provides useful Dockerfile syntax extensions that have been rejected by the moby project or haven't been addressed in a long time.

- [Getting started](#getting-started)
- [Features](#features)
  - [INCLUDE+](#include)
  - [ENVFILE+](#envfile)
- [Roadmap](#roadmap)
- [Feedback](#feedback)

## Getting started

First, you need to make sure you are running a compatible version of Docker:
- if you are using Docker 20.10+, you're all set!
- if you are using Docker 18.09+, then you need to export the following environment variable: `DOCKER_BUILDKIT=1`
- if you are using an older version of Docker, you are out of luck. Sorry!

Once your Docker is set, you just need to add the following line as your first line in your Dockerfile:

```Dockerfile
# syntax = edrevo/dockerfile-plus
```

That's it!

## Features

Note: All Dockerfile+ commands will end up with a `+` sign to avoid any potential future collisions with Dockerfile commands.

### INCLUDE+

`INCLUDE+` will import the verbatim contents of another file into your Dockerfile. Here's an example Dockerfile which uses the `INCLUDE+` instruction:

```Dockerfile
# syntax = edrevo/dockerfile-plus

FROM alpine

INCLUDE+ Dockerfile.common

ENTRYPOINT [ "mybin" ]
```

If Dockerfile.common contained a single line that said `RUN echo "Hello World"`, then the resulting Docker image would be identical to the one generated by this Dockerfile:


```Dockerfile
FROM alpine

RUN echo "Hello World"

ENTRYPOINT [ "mybin" ]
```

### ENVFILE+

docker-compose has had support for envfiles for a while now, but Dockerfile hasn't. The `ENVFILE+` instruction brings that support to Dockerfile! If you `ENVFILE+` a .env file, each line will be treated as an `ENV` definition. Here's an example:

```Dockerfile
# syntax = edrevo/dockerfile-plus

FROM alpine

ENVFILE+ prod.env

ENTRYPOINT [ "mybin" ]
```

If prod.env has the following:

```env
FOO=Hello
BAR=World
```

The resulting Docker image would be equivalent to the one generated by this standard Dockerfile:

```Dockerfile
# syntax = edrevo/dockerfile-plus

FROM alpine

ENV FOO=Hello

ENV BAR=World

ENTRYPOINT [ "mybin" ]
```

## Roadmap

The next features in line would be:

- `RUN+ --no-cache`, which would disable the cache only for a specific RUN step (useful for non-idempotent commands, for example those that clone git repos)
- `TAG` command
- improvements to .dockerignore, like recursive dockerignore files

## Feedback

Found a bug? Want to contribute a PR? Want to improve documentation or add a cool logo for the project? All contributions are welcome!

### Development environment

Install cargo (you can use [rustup.rs](https://rustup.rs/)) and run:

```bash
$ cargo build
```

### Creating a local release of the Buildkit frontend

```bash
$ docker build -f dockerfile-plus/Dockerfile .
```