datoma/hadolint repository overview

⁠Haskell Dockerfile Linter

A smarter Dockerfile linter that helps you build best practice⁠ Docker images. The linter is parsing the Dockerfile into an AST and performs rules on top of the AST. It is standing on the shoulders of ShellCheck⁠ to lint the Bash code inside RUN instructions.

:globe_with_meridians: Check the online version on hadolint.github.io/hadolint⁠

⁠How to use

You can run hadolint locally to lint your Dockerfile.

hadolint <Dockerfile>
hadolint --ignore DL3003 --ignore DL3006 <Dockerfile> # exclude specific rules
hadolint --trusted-registry my-company.com:500 <Dockerfile> # Warn when using untrusted FROM images

Docker comes to the rescue to provide an easy way how to run hadolint on most platforms. Just pipe your Dockerfile to docker run:

docker run --rm -i hadolint/hadolint < Dockerfile

⁠Install

You can download prebuilt binaries for OSX, Windows and Linux from the latest release page⁠. However, if it doesn't work for you, please fall back to Docker, brew or source installation.

If you are on OSX you can use brew⁠ to install hadolint.

brew install hadolint

On Windows you can use scoop⁠ to install hadolint.

scoop install hadolint

As shown before, hadolint is available as a Docker container:

docker pull hadolint/hadolint

If you need a Docker container with shell access, use the Debian or Alpine variants of the Docker image:

docker pull hadolint/hadolint:latest-debian
docker pull hadolint/hadolint:latest-alpine

You can also build hadolint locally. You need Haskell⁠ and the stack⁠ build tool to build the binary.

git clone https://github.com/hadolint/hadolint
cd hadolint
stack install

⁠Configure

hadolint supports specifying the ignored rules using a configuration file. The configuration file should be in yaml format. This is one valid configuration file as an example:

ignored:
  - DL3000
  - SC1010

Additionally, hadolint can warn you when images from untrusted repositories are being used in Dockerfiles, you can append the trustedRegistries keys to the configuration file as shown below:

ignored:
  - DL3000
  - SC1010

trustedRegistries:
  - docker.io
  - my-company.com:5000

Configuration files can be used globally or per project. By default, hadolint will look for a configuration file in the current directory with the name .hadolint.yaml

The global configuration file should be placed in the folder specified by XDG_CONFIG_HOME, with the name hadolint.yaml. In summary, the following locations are valid for the configuration file, in order or preference:

• $PWD/.hadolint.yaml
• $XDG_CONFIG_HOME/hadolint.yaml
• ~/.config/hadolint.yaml

In windows, the %LOCALAPPDATA% environment variable is used instead of XDG_CONFIG_HOME

Additionally, you can pass a custom configuration file in the command line with the --config option

hadolint --config /path/to/config.yaml Dockerfile

To pass a custom configuration file (using relative or absolute path) to a container, use the following command:

docker run --rm -i -v ./your/path/to/hadolint.yaml:/root/.config/hadolint.yaml hadolint/hadolint < Dockerfile

⁠Inline ignores

It is also possible to ignore rules by using a special comment directly above the Dockerfile instruction you want to make an exception for. Ignore rule comments look like # hadolint ignore=DL3001,SC1081. For example:

# hadolint ignore=DL3006
FROM ubuntu

# hadolint ignore=DL3003,SC1035
RUN cd /tmp && echo "hello!"

Inline ignores will only work if place directly above the instruction.

⁠Integrations

To get most of hadolint it is useful to integrate it as a check to your CI or to your editor to lint your Dockerfile as you write it. See our [Integration][] docs.

• [Code Review Platform Integrations][]
• [Continuous Integrations][]
• [Editor Integrations][]

⁠Rules

An incomplete list of implemented rules. Click on the error code to get more detailed information.

• Rules with the prefix DL originate from hadolint. Take a look at Rules.hs to find the implementation of the rules.

• Rules with the SC prefix originate from ShellCheck (Only the most common rules are listed, there are dozens more)

Please [create an issue][] if you have an idea for a good rule.

⁠Develop

If you are an experienced Haskeller we would be really thankful if you would tear our code apart in a review.

⁠Setup

1. Clone repository

   git clone --recursive [email protected]:hadolint/hadolint.git
   

   Copy

2. Install the dependencies

   stack install
   

   Copy

⁠REPL

The easiest way to try out the parser is using the REPL.

# start the repl
stack repl
# overload strings to be able to use Text
:set -XOverloadedStrings
# import parser library
import Language.Docker
# parse instruction and look at AST representation
parseText "FROM debian:jessie"

⁠Tests

Run unit tests.

stack test

Run integration tests.

./integration_test.sh

⁠AST

Dockerfile syntax is fully described in the [Dockerfile reference][]. Just take a look at [Syntax.hs][] in the language-docker project to see the AST definition.

⁠Alternatives

• RedCoolBeans/dockerlint⁠
• projectatomic/dockerfile_lint⁠