{"id":14975905,"url":"https://github.com/zavoloklom/docker-compose-linter","last_synced_at":"2025-04-05T00:05:00.729Z","repository":{"id":255646673,"uuid":"845738739","full_name":"zavoloklom/docker-compose-linter","owner":"zavoloklom","description":"A command-line tool for validating and enforcing best practices in Docker Compose files.","archived":false,"fork":false,"pushed_at":"2025-03-24T03:08:39.000Z","size":4074,"stargazers_count":77,"open_issues_count":19,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T23:03:46.883Z","etag":null,"topics":["dclint","devops","devops-tools","docker","docker-compose","docker-compose-linter","linter"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zavoloklom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-21T20:45:51.000Z","updated_at":"2025-03-25T14:42:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"0173657c-c846-41c9-8bdd-d7469b687808","html_url":"https://github.com/zavoloklom/docker-compose-linter","commit_stats":{"total_commits":8,"total_committers":2,"mean_commits":4.0,"dds":0.25,"last_synced_commit":"c6f88964a174120041fff1b7744b3edde2f8c49e"},"previous_names":["zavoloklom/docker-compose-linter"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zavoloklom%2Fdocker-compose-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zavoloklom%2Fdocker-compose-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zavoloklom%2Fdocker-compose-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zavoloklom%2Fdocker-compose-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zavoloklom","download_url":"https://codeload.github.com/zavoloklom/docker-compose-linter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dclint","devops","devops-tools","docker","docker-compose","docker-compose-linter","linter"],"created_at":"2024-09-24T13:52:50.411Z","updated_at":"2025-04-05T00:05:00.708Z","avatar_url":"https://github.com/zavoloklom.png","language":"TypeScript","funding_links":["https://www.paypal.com/donate/?hosted_button_id=ZKLT8EJ4KWA6L","https://www.buymeacoffee.com/zavoloklom"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD013 MD033 --\u003e\n\u003ch1 align=\"center\"\u003e\n    \u003cimg src=\"./docs/images/logo-grey.svg\" alt=\"Docker Compose Linter Logo\" height=\"192\" width=\"auto\" /\u003e\n    \u003cbr\u003e\n    Docker Compose Linter\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.npmjs.com/package/dclint\" target=\"_blank\" rel=\"noopener noreferrer nofollow\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/dclint?style=for-the-badge\" alt=\"Latest NPM Release Version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://hub.docker.com/r/zavoloklom/dclint\" target=\"_blank\" rel=\"noopener noreferrer nofollow\"\u003e\u003cimg src=\"https://img.shields.io/docker/v/zavoloklom/dclint?style=for-the-badge\u0026label=Docker%20Hub\" alt=\"Latest Docker Hub Release Version\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://app.codacy.com/gh/zavoloklom/docker-compose-linter/dashboard?utm_source=gl\u0026amp;utm_medium=referral\u0026amp;utm_content=\u0026amp;utm_campaign=Badge_grade\" target=\"_blank\" rel=\"noopener noreferrer nofollow\"\u003e\u003cimg src=\"https://img.shields.io/codacy/grade/2897b4940d094899ba59f1d287cdbd86?style=for-the-badge\u0026logo=codacy\u0026label=Code%20Quality\" alt=\"Codacy Code Quality Score\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/codacy/coverage/2897b4940d094899ba59f1d287cdbd86?style=for-the-badge\u0026label=Coverage\" alt=\"Code Coverage Score\"\u003e\n    \u003ca href=\"https://conventionalcommits.org\" target=\"_blank\" rel=\"noopener noreferrer nofollow\"\u003e\u003cimg src=\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits\u0026logoColor=whit\u0026style=for-the-badge\" alt=\"Conventional Commits\"\u003e\u003c/a\u003e\n    \u003ca href=\"#contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/all-contributors/zavoloklom/docker-compose-linter?color=ee8449\u0026style=for-the-badge\" alt=\"All Contributors\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-enable MD013 MD033 --\u003e\n\n\u003e **Note**: Docker Compose configurations vary greatly between different projects and setups. While DCLint is stable,\n\u003e there may be edge cases or unique setups that cause issues. If you encounter any problems or have suggestions, please\n\u003e feel free to [open an issue](https://github.com/zavoloklom/docker-compose-linter/issues/new/choose) or\n\u003e [submit a pull request](#contributing). Your feedback is highly appreciated!\n\nDocker Compose Linter (**DCLint**) is a utility designed to analyze, validate and fix Docker Compose files. It helps\nidentify errors, style violations, and potential issues in Docker Compose files, ensuring your configurations are\nrobust, maintainable, and free from common pitfalls.\n\n## Features\n\n- **Error Detection**: Identifies syntax errors and common issues in Docker Compose files.\n- **Style Enforcement**: Enforces best practices and style guidelines for maintainable configurations.\n- **Flexible Integration**: Can be used locally, in Docker, or integrated into CI/CD pipelines.\n- **Configurable Rules**: Customize the linter's behavior and rules according to your project's needs.\n- **Auto-fixable Rules**: Some rules include an auto-fix mode, allowing you to automatically format and correct certain\n  issues in your files.\n- **Comments Support**: After automated sorting and fixing, comments remain in the correct place, ensuring no important\n  information is lost during the formatting process.\n- **Anchor Support:** Supports YAML anchors for shared configuration sections, with\n  [some limitations](#anchor-handling).\n\n## Table of Contents\n\n- [Usage with Node.js](#usage-with-nodejs)\n- [Usage with Docker](#usage-with-docker)\n- [Usage as a NPM Package](#usage-as-a-npm-package)\n- [Rules and Errors](#rules-and-errors)\n- [Configuration](#configuration)\n- [Integration with CI/CD Pipeline](#integration-with-cicd-pipeline)\n- [Alternatives](#alternatives)\n- [Contributing](#contributing)\n- [Contributors](#contributors)\n- [Changelog](#changelog)\n- [License](#license)\n- [Contacts and Support](#contacts-and-support)\n\n## Usage with Node.js\n\nYou can install Docker Compose Linter globally or use it directly with npx.\n\n\u003e **Note:** DCLint requires Node.js version 18 or higher.\n\nTo install it globally:\n\n```shell\nnpm install --g dclint\n```\n\nAnd then run by command:\n\n```shell\ndclint .\n```\n\nIf you prefer not to install it globally, you can run the linter directly using npx:\n\n```shell\nnpx dclint .\n```\n\nThis command will lint your Docker Compose files in the current directory.\n\n### Linting Specific Files and Directories\n\nTo lint a specific Docker Compose file or a directory containing such files, specify the path relative to your project\ndirectory:\n\n```shell\nnpx dclint /path/to/docker-compose.yml\n```\n\nTo lint all Docker Compose files in a specific directory, use the path to the directory:\n\n```shell\nnpx dclint /path/to/directory\n```\n\nIn this case, `dclint` will search the specified directory for files matching the following pattern\n`/^(docker-)?compose.*\\.ya?ml$/`.\n\nIt will handle all matching files within the directory and, if [recursive search](./docs/cli.md#-r---recursive) is\nenabled, also in any subdirectories.\n\nFiles and directories like `node_modules`, `.git,` or others specified in the exclusion list will be ignored.\n\n### Display Help and Options\n\nTo display help and see all available options:\n\n```shell\nnpx dclint -h\n```\n\nFor more details about available options and formatters, please refer to the [CLI Reference](./docs/cli.md) and\n[Formatters Reference](./docs/formatters.md).\n\n## Usage with Docker\n\n### Pull the Docker Image\n\nFirst, pull the Docker image from the repository:\n\n```shell\ndocker pull zavoloklom/dclint\n```\n\n### Run the Linter in Docker\n\nTo lint your Docker Compose files, use the following command. This command mounts your current working directory\n`${PWD}` to the `/app` directory inside the container and runs the linter:\n\n```shell\ndocker run -t --rm -v ${PWD}:/app zavoloklom/dclint .\n```\n\n### Linting Specific Files and Directories in Docker\n\nIf you want to lint a specific Docker Compose file or a directory containing such files, specify the path relative to\nyour project directory:\n\n```shell\ndocker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/docker-compose.yml\n```\n\n```shell\ndocker run -t --rm -v ${PWD}:/app zavoloklom/dclint /app/path/to/directory\n```\n\n### Display Help in Docker\n\nTo display help and see all available options:\n\n```shell\ndocker run -t --rm -v ${PWD}:/app zavoloklom/dclint -h\n```\n\nFor more information about available options and formatters, please refer to the [CLI Reference](./docs/cli.md) and\n[Formatters Reference](./docs/formatters.md).\n\n## Usage as a NPM Package\n\nThe `dclint` can be integrated directly into your JS code, allowing you to run linting checks programmatically and\nformat the results as desired. Below are examples of how to use `dclint` as a library in both CommonJS and ES module\nformats.\n\nFirst you need to install it:\n\n```shell\nnpm install --save-dev dclint\n```\n\n### Example with CommonJS\n\n```javascript\nconst { DCLinter } = require('dclint');\n\n(async () =\u003e {\n  const linter = new DCLinter();\n\n  const lintResults = await linter.lintFiles(['.'], true);\n  const formattedResults = await linter.formatResults(lintResults, 'stylish');\n\n  console.log(formattedResults);\n})();\n```\n\n### Example with ES Module\n\n```javascript\nimport { DCLinter } from 'dclint';\n\nconst linter = new DCLinter();\n\nconst lintResults = await linter.lintFiles(['.'], true);\nconst formattedResults = await linter.formatResults(lintResults, 'stylish');\n\nconsole.log(formattedResults);\n```\n\n## Rules and Errors\n\nDocker Compose Linter includes set of rules to ensure your Docker Compose files adhere to best practices. Detailed\ndocumentation for each rule and the errors that can be detected by the linter is available here:\n\n- [Rules Documentation](./docs/rules.md)\n- [Errors Documentation](./docs/errors.md)\n\nDCLint uses the [yaml](https://github.com/eemeli/yaml) library for linting and formatting Docker Compose files. This\nensures that any configuration files you check are compliant with YAML standards. Before any rule checks are applied,\ntwo important validations are performed, which cannot be disabled - [YAML Validity Check](./docs/errors/invalid-yaml.md)\nand [Docker Compose Schema Validation](./docs/errors/invalid-schema.md).\n\n### Disabling Rules via Comments\n\nYou can disable specific linting rules or all rules in your Docker Compose files using comments. These comments can be\nused either to disable rules for the entire file or for individual lines. For detailed instructions on how to use these\ncomments, check out the full documentation here: [Using Configuration Comments](./docs/configuration-comments.md).\n\n### Anchor Handling\n\nDocker Compose Linter provides support for YAML anchors specifically during schema validation, which enables the reuse\nof configuration sections across different services for cleaner and more maintainable files.\n\nHowever, note that anchors are neither validated by individual linting rules nor automatically fixed when using the\n`--fix` flag.\n\nWhen multiple anchors are required in a Docker Compose file, use the following syntax:\n\n```yaml\nx-anchor1: \u0026anchor1\n  ports:\n    - 80\nx-anchor2: \u0026anchor2\n  ports:\n    - 81\n\nservices:\n  image: image\n  \u003c\u003c: [ *anchor1, *anchor2 ]\n```\n\nThis approach, which combines anchors in a single \u003c\u003c line, is preferable to defining each anchor on separate lines (\ne.g., `\u003c\u003c : *anchor1` followed by `\u003c\u003c : *anchor2`).\n\nMore information on YAML merge syntax is available in the\n[official YAML documentation](https://yaml.org/type/merge.html) and in\n[known issue with Docker Compose](https://github.com/docker/compose/issues/10411).\n\nFor an example of anchor usage, refer to the sample Compose file in `tests/mocks/docker-compose.anchors.yml`.\n\n## Configuration\n\nDCLint allows you to customize the set of rules used during linting to fit your project's specific needs. You can\nconfigure which rules are applied, their severity levels, and additional behavior settings using a configuration file.\n\n### Supported Configuration File Formats\n\nDCLint supports flexible configuration options through the use of\n[cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). This means you can use various formats to configure the\nlinter, including JSON, YAML, and JavaScript files.\n\nFor example:\n\n- `.dclintrc` (JSON, YAML, or JavaScript)\n- `dclint.config.js` (JavaScript)\n- A `dclint` key inside your `package.json`\n\n### Example Configuration File\n\nHere is an example of a configuration file using JSON format:\n\n```json\n{\n  \"rules\": {\n    \"no-version-field\": 0,\n    \"require-quotes-in-ports\": 1,\n    \"services-alphabetical-order\": 2\n  },\n  \"quiet\": false,\n  \"debug\": true,\n  \"exclude\": [\n    \"tests\"\n  ]\n}\n```\n\n- **rules**: Customize which rules to apply and their severity levels (`0` - Disabled, `1` - Warning, `2` - Error).\n- **quiet**: Suppresses non-error output if set to `true`.\n- **debug**: Enables debug mode with additional output if set to `true`.\n- **exclude**: Specifies files or directories to exclude from linting.\n\nTo enable editor autocompletion in a JSON configuration file, add a `$schema` property. If you have installed `dclint`:\n\n```json\n{\n  \"$schema\": \"./node_modules/dclint/schemas/linter-config.schema.json\"\n}\n```\n\nOtherwise:\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/zavoloklom/docker-compose-linter/refs/heads/main/schemas/linter-config.schema.json\"\n}\n```\n\n### Configure Rules\n\nIn addition to enabling or disabling rules, some rules may support custom parameters to tailor them to your specific\nneeds. For example, the [require-quotes-in-ports](./docs/rules/require-quotes-in-ports-rule.md) rule allows you to\nconfigure whether single or double quotes should be used around port numbers. You can configure it like this:\n\n```json\n{\n  \"rules\": {\n    \"require-quotes-in-ports\": [\n      2,\n      {\n        \"quoteType\": \"double\"\n      }\n    ]\n  }\n}\n```\n\nIn this example, the require-quotes-in-ports rule is enabled at the error level and configured to enforce double quotes\naround ports.\n\n## Integration with CI/CD Pipeline\n\nAutomate linting as part of your CI/CD pipeline by adding the Docker run command to your pipeline script. This ensures\nthat your Docker Compose files are always checked for errors before deployment.\n\n### GitLab CI Example\n\n```yaml\nlint-docker-compose:\n  image:\n    name: zavoloklom/dclint:alpine\n    entrypoint: [ '' ]\n  script:\n    - /bin/dclint . -r -f codeclimate -o gl-codequality.json\n  artifacts:\n    reports:\n      codequality: gl-codequality.json\n```\n\n## Alternatives\n\nConsider these alternative tools for Docker Compose linting and validation:\n\n- [kics](https://github.com/Checkmarx/kics)\n- [yamllint](https://github.com/adrienverge/yamllint)\n\nAnd this tools for Docker Compose formatting and fixing:\n\n- [compose_format](https://github.com/funkwerk/compose_format/)\n- [yamlfix](https://github.com/lyz-code/yamlfix)\n\n## Contributing\n\nIf you encounter any issues or have suggestions for improvements, feel free to open an\n[issue](https://github.com/zavoloklom/docker-compose-linter/issues) or submit a\n[pull request](https://github.com/zavoloklom/docker-compose-linter/pulls).\n\nIf you'd like to contribute to this project, please read through the [CONTRIBUTING.md](./CONTRIBUTING.md) file.\n\nPlease note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating\nin this project, you agree to abide by its terms.\n\n- [How to set up the project](./CONTRIBUTING.md)\n- [How to add a new rule](./CONTRIBUTING.md#how-to-add-a-new-rule)\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji keys explanation](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/szymon-filipiak\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/25361786?v=4?s=100\" width=\"100px;\" alt=\"Szymon Filipiak\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSzymon Filipiak\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=szymon-filipiak\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://salzsee.info/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/99911?v=4?s=100\" width=\"100px;\" alt=\"Ben Rexin\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBen Rexin\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=salzig\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=salzig\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=salzig\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://adaliszk.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5189131?v=4?s=100\" width=\"100px;\" alt=\"Ádám Liszkai\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eÁdám Liszkai\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/discussions?discussions_q=author%3Aadaliszk\" title=\"Participated in discussions or provided ideas\"\u003e💡\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://adamvig.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5354752?v=4?s=100\" width=\"100px;\" alt=\"Adam Vigneaux\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAdam Vigneaux\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=AdamVig\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/zavoloklom/docker-compose-linter/commits?author=AdamVig\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.\nContributions of any kind welcome!\n\n## Changelog\n\nThe changelog is automatically generated based on\n[semantic-release](https://github.com/semantic-release/semantic-release) and\n[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).\n\nSee the [CHANGELOG.md](./CHANGELOG.md) file for detailed lists of changes for each version.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information.\n\n## Contacts and Support\n\nIf you find this repository helpful, kindly consider showing your appreciation by giving it a star ⭐.\n\nIf you have any questions or suggestions, feel free to reach out:\n\n- **Email**: [s.kupletsky@gmail.com](mailto:s.kupletsky@gmail.com)\n- **Х/Twitter**: [zavoloklom](https://x.com/zavoloklom)\n- **Instagram**: [zavoloklom](https://www.instagram.com/zavoloklom/)\n- **GitHub**: [zavoloklom](https://github.com/zavoloklom)\n\nAlso, you can support this project with a donation:\n\n[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://www.paypal.com/donate/?hosted_button_id=ZKLT8EJ4KWA6L)\n[![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/zavoloklom)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzavoloklom%2Fdocker-compose-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzavoloklom%2Fdocker-compose-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzavoloklom%2Fdocker-compose-linter/lists"}