DCLint
The Docker Compose Linter project describes the tool as follows:
A command-line tool for validating and enforcing best practices in Docker Compose files.
DCLint checks Docker Compose files against best practices, such as quoted
port mappings and a consistent key order in each service. These checks keep
docker-compose.yml readable as services come and go.
Vortex comes with a pre-configured DCLint
ruleset for its
Docker Compose files.
This page is for developers who change docker-compose.yml. It shows how
to run DCLint the way CI does, fix what it reports and tell which findings
fail the build.
Installation
Vortex doesn't install DCLint in the project. To run it locally, install it on your machine by following the DCLint usage instructions. In CI, DCLint runs from its official Docker image.
The installer selects DCLint by default. If you deselect it in the
Development tools prompt, the installer removes .dclintrc and the
dclint directives in docker-compose.yml. It also removes the DCLint
step from the CI configuration of every supported provider.
Usage
To lint the Docker Compose files, run the following command from the project root:
dclint .
To fix the problems that DCLint can fix automatically, such as the order of
service keys and unquoted ports, add the --fix flag:
dclint --fix .
Confirm that the check passed: echo $?, run right after DCLint, prints 0
when DCLint found no errors. Warnings appear in the output and leave the
exit code at 0.
Configuration
Global configuration lives in the
.dclintrc file.
It sets each rule it lists to 1 of 3 levels:
0turns the rule off.1reports a warning, which doesn't fail the check.2reports an error, which fails the check.
The file turns off the following 4 rules:
no-build-and-imageservices-alphabetical-orderno-unbound-port-interfacesrequire-project-name-field
It also sets service-keys-order to 1 and configures it with 8 groups of
keys. That rule checks that the keys of every service in
docker-compose.yml follow the same order, from core definitions such as
build and image to operational metadata such as labels. Diffs then
stay small and services stay comparable. Every other rule keeps the level
DCLint gives it by default.
A directive in docker-compose.yml turns off a fifth rule, for 1 line
only. With migration enabled, the database2 service has a
dclint disable-line directive for no-duplicate-exported-ports, with the
reason next to it.
DCLint reads the container-only port 3306 as a host port that the
database service already uses. Docker publishes each container-only port
on its own random host port, so the 2 services don't clash.
Ignore violations
To ignore all DCLint rules in a file, add this comment as the first line of the file:
# dclint disable
services:
cli:
build: .
To ignore specific rules in a file, list them after dclint disable in the
same comment, separated by spaces:
# dclint disable require-quotes-in-ports service-keys-order
To ignore rules for a single line, add a disable-line comment at the end
of that line or on its own line right before it. The following example
ignores 1 rule for 1 port:
services:
nginx:
ports:
# dclint disable-line require-quotes-in-ports
- 8080:8080
Continuous integration
DCLint runs in the lint job of the continuous integration
pipeline and fails the build when
it reports an error. Warnings, such as unquoted ports or service keys out of
order, appear in the job log without failing the build.
Ignore failures
To let the build pass despite errors, set the
VORTEX_CI_DCLINT_IGNORE_FAILURE CI variable to 1. DCLint still runs and
prints every violation in the job log, so you can see what you're letting
through.