If you’re a developer working with Dockerfiles, then you know how important it is to keep your files clean and organized. But what if you don’t have time to clean your files every day? That’s where Hadolint comes in. Hadolint is a tool that helps you lint your Dockerfiles. It’s a simple tool that runs on each file in your project and helps you to catch errors and improve the organization of your code. To use Hadolint, first add it to your project’s dependencies:
yarn add hadolint
Next, create a file called “config.js” in your project root: var hadolint = require ( ‘hadolint’ ); var config = { // … other settings }; hadolint . init ( config ); Now, when you run hadolint on your project, it will start automatically checking for errors and improving the organization of your code. You can also control how often it runs by setting its options:
Dockerfiles define the content of Docker images as a set of instructions in a text file. The Dockerfile syntax is generally straightforward but there are some gotchas to avoid. Adhering to best practices while writing complex Dockerfiles in a team setting can be tricky unless you’re automatically validating your file’s content.
Hadolint is a Dockerfile linter that can spot common issues for you. It uses an abstract syntax tree (AST) to parse your Dockerfile against predefined rulesets. Hadolint also incorporates ShellCheck so it can lint the shell scripts in your Dockerfile’s RUN instructions too.
Getting Started
Hadolint is distributed in multiple formats. You can quickly get started by downloading the latest pre-compiled binary for your operating system from the project’s GitHub releases page. Hadolint’s also got its own own Docker image, hadolint/hadolint, if you’d rather not use the binary directly. As a final option, you can access Hadolint via the web for experimentation.
Linting a Dockerfile
Pass Hadolint the path to a Dockerfile to start a new scan:
If you’re using the Dockerized version, it’s easiest to pipe the contents of your file into a Hadolint container:
The scan results will be shown in your terminal. In this example, Hadolint is suggesting that the Dockerfile’s RUN apt-get install statement is unsafe as it doesn’t specify explicit package versions. The content of your image could change in-between builds, potentially creating confusing problems.
What Does Hadolint Look For?
Hadolint has dozens of built-in rules that check for common configuration and security issues. The linter aims to make your Dockerfiles compliant with the image building best practices suggested by Docker.
Included checks cover use of non-root final users, referencing a relative path in a WORKDIR statement, adding multiple HEALTHCHECK instructions, and not using explicitly pinned tags and versions. As Hadolint also inherits the ShellCheck ruleset, it’ll surface common Bash scripting problems which that tool identifies too.
Rules are identified as numbers prefixed with either HL or SC. HL rules are part of Hadolint whereas SC entries come from ShellCheck. Each check is given a severity from Error through to Info. If you get Errors in your scan results, those should be the first issues you resolve.
Customizing Configuration
Hadolint is configured via a .hadolint.yaml file. It will search multiple locations including your working, .config, and home directories. Only the first found file is used – there’s no merging between locations.
The config file lets you customize your scans by ignoring rules and changing their severities. While the default ruleset covers recommended best practices, you might find some checks don’t apply in your environment. Committing a .hadolint.yaml file alongside your Dockerfile lets you tailor Hadolint scans accordingly. Most config file fields are also supported as CLI flags and environment variables.
Rules are disabled by the ignored field. This should be a list of rule IDs:
If you need to lower a rule’s severity without disabling it entirely, use the override key instead. This also lets you promote a low severity issue to a higher level. Use this if you want to place greater emphasis on a particular issue.
This demotes rule DL3020 from its default “error” level to the less serious “warning.” This rule requires you use COPY instead of ADD when referencing files and folders in your build context.
You can adjust the global severity level too. Setting the failure-threshold field instructs Hadolint to exit with a failure status if any test reports an error at the given severity level:
This instruction means the Hadolint scan will fail if there’s either an error or a warning in its output.
You can disable exiting with a failure code using the no-fail: true config option or the –no-fail CLI flag. This will instruct Hadolint to exit with a 0 code irrespective of the actual test outcome. It can be useful if you want to include Hadolint as a non-blocking job in a CI pipeline.
Trusting Registries
Another use of the config file is to define trusted registries which you want to be able to reference in your Dockerfiles. When the trustedRegistries field is set, Hadolint will warn you when an image from another registry is used:
Label Schemas
Hadolint offers basic label linting too. This lets you enforce that labels added to your image by Dockerfile LABEL instructions comply with specified constraints. Here’s an example of how it works:
This config snippet defines data types for four labels you can use in your Dockerfile. notes is declared as an arbitrary text field while app-version must be a semver-compatible version identifier. built-at is marked as an RFC-3339 datetime string. You can get the full list of supported types in the Hadolint docs.
Hadolint permits use of labels that aren’t listed in your schema. You can disable this and restrict LABEL instructions to only those present in the schema by setting strict-labels: true or using the –strict-labels flag.
Output Formats
Several output formats are supported via the format option or –format flag. The default is tty which emits colorized output to your terminal. Colors can be disabled with the –no-color flag.
The following alternative formatters are available:
json – Provides the list of detected issues as a verbose JSON structure that’s ideal for use with your own scripts. checkstyle – A Checkstyle compatible report. codeclimate – A Code Climate compatible report. gitlab_codeclimate – Variation of the Code Climate report that works with GitLab’s integrated code quality features. This lets you view errors as a widget on merge request pages when running Hadolint with GitLab CI.
These output formats are ideal for using Hadolint programmatically or as part of a CI pipeline.
Summary
Hadolint automates the detection of Dockerfile issues. This helps your Docker images adhere to best practices and organizational standards. The default configuration is a good starting point but you can customize it to fit your needs by reclassifying and disabling rules.
You should consider integrating Hadolint with your CI tool to get instant reports as Dockerfile changes are committed. This accelerates code review by giving developers immediate visibility into problems. You can also use the tool locally while you work via community-supported editor extensions, providing an even shorter feedback loop.
