Docker Compose Linter

Note: Docker Compose configurations vary greatly between different projects and setups. While DCLint is stable, there may be edge cases or unique setups that cause issues. If you encounter any problems or have suggestions, please feel free to open an issue or submit a pull request. Your feedback is highly appreciated!

Docker Compose Linter (DCLint) is a utility designed to analyze, validate and fix Docker Compose files. It helps identify errors, style violations, and potential issues in Docker Compose files, ensuring your configurations are robust, maintainable, and free from common pitfalls.

Features

• Error Detection: Identifies syntax errors and common issues in Docker Compose files.
• Style Enforcement: Enforces best practices and style guidelines for maintainable configurations.
• Flexible Integration: Can be used locally, in Docker, or integrated into CI/CD pipelines.
• Configurable Rules: Customize the linter's behavior and rules according to your project's needs.
• Auto-fixable Rules: Some rules include an auto-fix mode, allowing you to automatically format and correct certain issues in your files.
• Comments Support: After automated sorting and fixing, comments remain in the correct place, ensuring no important information is lost during the formatting process.
• Anchor Support: Supports YAML anchors for shared configuration sections, with some limitations.

Getting Started

Installation with Node.js

You can install Docker Compose Linter locally in your project or use it directly with npx.

Note: DCLint requires Node.js version 18 or higher.

To install it locally:

npm install --save-dev dclint

Running the Linter with npx

If you prefer not to install it globally, you can run the linter directly using npx:

npx dclint .

This command will lint your Docker Compose files in the current directory.

Linting Specific Files and Directories

To lint a specific Docker Compose file or a directory containing such files, specify the path relative to your project directory:

npx dclint /path/to/docker-compose.yml

To lint all Docker Compose files in a specific directory, use the path to the directory:

npx dclint /path/to/directory

In this case, dclint will search the specified directory for files matching the following pattern /^(docker-)?compose.*\.ya?ml$/.

It will handle all matching files within the directory and, if recursive search is enabled, also in any subdirectories.

Files and directories like node_modules, .git, or others specified in the exclusion list will be ignored.

Display Help and Options

To display help and see all available options:

npx dclint -h

For more details about available options and formatters, please refer to the CLI Reference and Formatters Reference.

Usage with Docker

Pull the Docker Image

First, pull the Docker image from the repository:

docker pull zavoloklom/dclint

Run the Linter in Docker

To lint your Docker Compose files, use the following command. This command mounts your current working directory ${PWD} to the /app directory inside the container and runs the linter:

docker run -t --rm -v ${PWD}:/app zavoloklom/dclint .

Linting Specific Files and Directories in Docker

If you want to lint a specific Docker Compose file or a directory containing such files, specify the path relative to your project directory:

docker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/docker-compose.yml

docker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/directory

Display Help in Docker

To display help and see all available options:

docker run -t --rm -v ${PWD}:/app zavoloklom/dclint -h

For more information about available options and formatters, please refer to the CLI Reference and Formatters Reference.

Usage as a Library

The dclint library can be integrated directly into your code, allowing you to run linting checks programmatically and format the results as desired. Below are examples of how to use dclint as a library in both CommonJS and ES module formats.

Example with CommonJS

const { DCLinter } = require('dclint');

(async () => {
  const linter = new DCLinter();

  const lintResults = await linter.lintFiles(['.'], true);
  const formattedResults = await linter.formatResults(lintResults, 'stylish');

  console.log(formattedResults);
})();

Example with ES Module

import { DCLinter } from 'dclint';

const linter = new DCLinter();

const lintResults = await linter.lintFiles(['.'], true);
const formattedResults = await linter.formatResults(lintResults, 'stylish');

console.log(formattedResults);

Rules and Errors

Docker Compose Linter includes set of rules to ensure your Docker Compose files adhere to best practices. Detailed documentation for each rule and the errors that can be detected by the linter is available here:

• Rules Documentation
• Errors Documentation

DCLint uses the yaml library for linting and formatting Docker Compose files. This ensures that any configuration files you check are compliant with YAML standards. Before any rule checks are applied, two important validations are performed, which cannot be disabled - YAML Validity Check and Docker Compose Schema Validation.

Disabling Rules via Comments

You can disable specific linting rules or all rules in your Docker Compose files using comments. These comments can be used either to disable rules for the entire file or for individual lines. For detailed instructions on how to use these comments, check out the full documentation here: Using Configuration Comments.

Anchor Handling

Docker Compose Linter provides support for YAML anchors specifically during schema validation, which enables the reuse of configuration sections across different services for cleaner and more maintainable files.

However, note that anchors are neither validated by individual linting rules nor automatically fixed when using the --fix flag.

When multiple anchors are required in a Docker Compose file, use the following syntax:

x-anchor1: &anchor1
  ports:
    - 80
x-anchor2: &anchor2
  ports:
    - 81

services:
  image: image
  <<: [ *anchor1, *anchor2 ]

This approach, which combines anchors in a single << line, is preferable to defining each anchor on separate lines ( e.g., << : *anchor1 followed by << : *anchor2).

More information on YAML merge syntax is available in the official YAML documentation and in known issue with Docker Compose.

For an example of anchor usage, refer to the sample Compose file in tests/mocks/docker-compose.anchors.yml.

Configuration

DCLint allows you to customize the set of rules used during linting to fit your project's specific needs. You can configure which rules are applied, their severity levels, and additional behavior settings using a configuration file.

Supported Configuration File Formats

DCLint supports flexible configuration options through the use of cosmiconfig. This means you can use various formats to configure the linter, including JSON, YAML, and JavaScript files.

For example:

• .dclintrc (JSON, YAML, or JavaScript)
• dclint.config.js (JavaScript)
• A dclint key inside your package.json

Example Configuration File

Here is an example of a configuration file using JSON format:

{
  "rules": {
    "no-version-field": 0,
    "require-quotes-in-ports": 1,
    "services-alphabetical-order": 2
  },
  "quiet": false,
  "debug": true,
  "exclude": [
    "tests"
  ]
}

• rules: Customize which rules to apply and their severity levels (0 - Disabled, 1 - Warning, 2 - Error).
• quiet: Suppresses non-error output if set to true.
• debug: Enables debug mode with additional output if set to true.
• exclude: Specifies files or directories to exclude from linting.

To enable editor autocompletion in a JSON configuration file, add a $schema property. If you have installed dclint:

"$schema": "./node_modules/dclint/schemas/linter-config.schema.json",

Otherwise:

"$schema": "https://raw.githubusercontent.com/zavoloklom/docker-compose-linter/refs/heads/main/schemas/linter-config.schema.json",

Configure Rules

In addition to enabling or disabling rules, some rules may support custom parameters to tailor them to your specific needs. For example, the require-quotes-in-ports rule allows you to configure whether single or double quotes should be used around port numbers. You can configure it like this:

{
  "rules": {
    "require-quotes-in-ports": [
      2,
      {
        "quoteType": "double"
      }
    ]
  }
}

In this example, the require-quotes-in-ports rule is enabled at the error level and configured to enforce double quotes around ports.

Integrate into CI/CD Pipeline

Automate linting as part of your CI/CD pipeline by adding the Docker run command to your pipeline script. This ensures that your Docker Compose files are always checked for errors before deployment.

GitLab CI Example

lint-docker-compose:
  image:
    name: zavoloklom/dclint:alpine
    entrypoint: [ '' ]
  script:
    - /bin/dclint . -r -f codeclimate -o gl-codequality.json
  artifacts:
    reports:
      codequality: gl-codequality.json

Alternatives

Consider these alternative tools for Docker Compose linting and validation:

• kics
• checkov
• yamllint
• docker-compose-linter

And this tools for Docker Compose formatting and fixing:

• compose_format
• yamlfix

Contributing

If you encounter any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.

If you'd like to contribute to this project, please read through the CONTRIBUTING.md file.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.

• How to set up the project
• How to add a new rule

Changelog

The changelog is automatically generated based on semantic-release and conventional commits.

See the CHANGELOG.md file for detailed lists of changes for each version.

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Contact

If you have any questions or suggestions, feel free to reach out:

• Email: [email protected]
• Twitter: zavoloklom
• GitHub: zavoloklom