README.md

Dofigen

Dofigen is a Dockerfile generator using a simplified description in YAML or JSON format. It defines default values and behaviors that simplify the creation of Dockerfiles.

Dofigen is also made to use the Buildkit optimizations that speed-up the Docker image build by parallelizing the layer builds. It uses the --link option when adding files and the --mount=type=cache option when running scripts (when you define caches attribute). You can use Buildkit with the docker buildx build subcommand like this:

docker buildx build --cache-to=type=local,dest=.dockercache --cache-from=type=local,src=.dockercache -t my-app:latest --load .

A french DevOps said about it:

C'est une bouffée, Dofigen, dans ce monde de con...teneurs.

Report Bug · Request Feature

Getting Started

Prerequisites

Install Dofigen using one of the following options.

Cargo install

First install Cargo, the Rust package manager: https://doc.rust-lang.org/cargo/getting-started/installation.html

Then use the following command to install dofigen:

cargo install dofigen

Download the binary

You can download the Dofigen binary from the release page and add it to your path environment variable.

Use it with Docker

You can run Dofigen directly from its Docker image with the following command:

docker run --rm -it -v $(pwd):/app lenra/dofigen

(back to top)

How to use it

To generate a Dockerfile, you need to create a Dofigen file dofigen.yml and run the next command:

dofigen gen

Use the help options to understand how to override default behaviors:

$ dofigen gen --help
Generate the Dockerfile and .dockerignore files

Usage: dofigen generate [OPTIONS]

Options:
  -f, --file <FILE>      The input Dofigen file. Default search for the next files: dofigen.yml, dofigen.yaml, dofigen.json Use "-" to read from stdin
      --offline          The command won't load data from any URL. This disables extending file from URL and loading image tag
  -o, --output <OUTPUT>  The output Dockerfile file Define to - to write to stdout [default: Dockerfile]
  -l, --locked           Locked version of the dofigen definition
  -h, --help             Print help

To look further use the help command:

dofigen --help

Dofigen descriptor

The structure of the Dofigen descriptor was created to be simpler than the Dockerfile.

The JSON Schema of the Dofigen descriptor is available here.

Here is an example to generate the Dofigen Dockerfile:

builders:
  muslrust:
    fromImage: clux/muslrust:stable
    workdir: /app
    bind:
      - Cargo.toml
      - Cargo.lock
      - src/
    run:
      # Build with musl to work with scratch
      - cargo build --release
      # copy the generated binary outside of the target directory. If not the other stages won't be able to find it since it's in a cache volume
      - mv target/x86_64-unknown-linux-musl/release/dofigen /tmp/
    cache:
      # Cargo cache
      - /home/rust/.cargo
      # build cache
      - /app/target

# Runtime
workdir: /app
copy:
  - fromBuilder: muslrust
    paths: "/tmp/dofigen"
    target: "/bin/"
entrypoint: dofigen
cmd: --help
context:
  - "/src"
  - "/Cargo.*"

Extending external files

You can extend the Dofigen file with external files using the extend attribute. You can find some Dofigen templates on the Dofigen Hub repository. Here is an example of extending a Dofigen file:

extend:
  - https://raw.githubusercontent.com/lenra-io/dofigen/main/dofigen.yml

You can also override or merge the structure of the extended files:

extend:
  - https://raw.githubusercontent.com/lenra-io/dofigen/main/dofigen.yml
user: 1001

The lock file

Dofigen generates a lock file to keep the version of the Dofigen descriptor used to generate the Dockerfile. The lock file also keep the loaded resources and images tags to rebuild the Dockerfile with the same versions. To update the images and resources, you can use the dofigen update command. To regenerate the Dockerfile with the same versions, you can use the dofigen gen --locked command.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please open an issue with the tag "enhancement" or "bug". Don't forget to give the project a star! Thanks again!

Tests

To run the tests, use the following command:

cargo test --all-features

Generate the JSON Schema

To generate the JSON schema of the Dofigen file structure, use the following command:

cargo run -F json_schema -- schema

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Lenra - @lenra_dev - [email protected]

Project Link: https://github.com/lenra-io/dofigen

(back to top)