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 order of keys within each service, so
docker-compose.yml stays 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. After reading
it, you can run DCLint the way CI does, fix what it reports, and tell which
of its 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 the .dclintrc
configuration file, the dclint directives in docker-compose.yml, and
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: run echo $? straight after DCLint. It
prints 0 when DCLint found no errors. Warnings still appear in the
output, but they don't change the exit code.
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 keeps the keys of every service in docker-compose.yml in
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 rule the file doesn't list keeps the level DCLint
gives it by default.
docker-compose.yml turns off 1 more rule for a single line. With
migration enabled, the database2 service carries 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.
Ignoring
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.
Ignoring 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.