{"id":23683514,"url":"https://github.com/zanetworker/dockument","last_synced_at":"2025-09-02T11:31:35.891Z","repository":{"id":64302988,"uuid":"125109160","full_name":"zanetworker/dockument","owner":"zanetworker","description":"DOCKument is a tool to auto-generate documentation for your Dockerfiles \u0026 Docker Images the way you would an API.","archived":false,"fork":false,"pushed_at":"2018-04-23T12:38:00.000Z","size":52342,"stargazers_count":17,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T03:26:26.696Z","etag":null,"topics":["docker","docker-images","dockerfiles"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zanetworker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-13T20:16:50.000Z","updated_at":"2024-06-20T03:26:26.697Z","dependencies_parsed_at":"2023-01-15T09:45:17.998Z","dependency_job_id":null,"html_url":"https://github.com/zanetworker/dockument","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanetworker%2Fdockument","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanetworker%2Fdockument/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanetworker%2Fdockument/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanetworker%2Fdockument/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zanetworker","download_url":"https://codeload.github.com/zanetworker/dockument/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231780340,"owners_count":18425543,"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":["docker","docker-images","dockerfiles"],"created_at":"2024-12-29T20:08:13.454Z","updated_at":"2024-12-29T20:08:14.230Z","avatar_url":"https://github.com/zanetworker.png","language":"Go","readme":"# DOCKument\n\n[![Build Status](http://zanetworkercicd.eu.ngrok.io/api/badges/zanetworker/dockument/status.svg?branch=master)](http://zanetworkercicd.eu.ngrok.io/api/badges/zanetworker/dockument/status.svg?branch=master)\n\nDOCKument is a tool that helps you auto-generate documentation for your Dockerfiles and Docker images the way you would an API.\n\nMatthias Lübken gave an example on how to use \"API\" like labels to describe important information in the Dockerfile (e.g., resources used, exposed ports, dependencies, etc) [here](https://github.com/luebken/currentweather/blob/master/Dockerfile). This project makes use of similar label patterns to fetch important data in Dockerfiles / Docker images and create Dockumentation for it automagically. Furthermore, it improves on the work done by Matthias to expose various kinds of information that can be fetched from Docker images.\n\n\n\nCheck the blog post [here](http://www.adelzaalouk.me/2018/dockument/)\n\n## Getting Started\n\nTo get started with `Dockument`, you can download the corresponding binary for your OS (Darwin, Linux, Windows) from the releases section. Or you can clone this repository and build the project locally.\n\n### Clone and build\n\nYou need to install `make` and `Go` on your system before proceeding.\n\n```bash\ngit clone https://github.com/zanetworker/dockument.git\ncd dockument\n\n# build dockument binary if you have go installed\nmake OS=\u003cdarwin|linux|windows\u003e install\n\n# execute dockument for command overview\ndockument\n\n# build dockument binary \nmake OS=\u003cdarwin|linux|windows\u003e dry\n\n# execute dokcument command for overview\n./dockument\n```\n\n### Usage\n\n[![asciicast](https://asciinema.org/a/pdVCkPpvz7OAdjYpuOz4gMY1j.png)](https://asciinema.org/a/pdVCkPpvz7OAdjYpuOz4gMY1j)\n\nWith DOCKument you have the option to fetch important information about your Dockerfile or Docker Image direcly from the command line or create a markdown document that you can add to your git REPO.\n\n\n**Fetching Information from a Dockerfile or a Docker Image**\n\nFor example, if you type `dockument deps --dockerfile \"../examples/Dockerfile\"` or `dockument deps --image \"repo/name:tag\"`, you will get the following output:\n\n```bash\n### Dependency RABBIT ###\n\tApplication: rabbit\n\tImage: \"rabbit:latest\"\n\tDescription: \"The rabbit\"\n\tPorts: [\"5271\"]\n\tRequired: \"true\"\n\n### Dependency REDIS ###\n\tApplication: redis\n\tImage: \"redis:latest\"\n\tDescription: \"For caching results from OWM API.\"\n\tPorts: [\"6379\"]\n\tRequired: \"true\"\n``` \n\nOn the other hand, to create a markdown DOCKument, you can use `dockument create --dockerfile \"../examples/Dockerfile\" -o \"$HOME/dockumentation.md\"` or `dockument create --image \"repo/name:tag\" -o \"$HOME/dockumentation.md\"` . The output will be a file similar to the one [here](\"https://github.com/zanetworker/dockument/blob/master/examples/dockumentation.md\")\n\n**Creating a Dockumentation markdown to describe your image or Dockerfile** \n\nTo create Dockumentation for a Dockerfile, you can simply type (as an example):\n\n```bash\ndockument create --dockerfile \"examples/Dockerfile\" -o \"$HOME/dockumentation.md\"\n```\n\nand for a Docker Image\n\n```bash\ndockument create -i \"zanetworker/document:latests\" -o \"$HOME/dockumentation.md\"\n```\n\nFor more information, use `dockument help` to find out about the available commands.\n\n\n### Pre-reqs\n\nThere are two types of labels that `Dockument` supports, these are: \n\n- **Misc Lables**: these are random / non-standard  labels defined in your Docker image, basically any label that does not follow the pattern described below.\n- **Standardized Labels**: These are the gems of `Dockument`, these labels are the ones used to expose the important information about your Dockerfile / Docker image. They follow a pattern, always prefiexed with **api.Type.***\n\nYou can use `Dockument` to print or create a documentation of random metadata in your Dockerfile or Docker images, however, that is not very useful. To utilize the fully-fledged functionality of Dockument, define labels in your Docker images that follow the below pattern.\n\n**For Dependencies**:\n\nWill this containerized application have dependencies on other applications?\n\n```dockerfile\nLABEL api.DEPENDENCY.redis=\"\"\\\n      api.DEPENDENCY.redis.image=\"redis:latest\"\\\n      api.DEPENDENCY.redis.port=\"6379\"\\\n      api.DEPENDENCY.redis.about=\"For caching results from OWM API.\"\\\n      api.DEPENDENCY.redis.mandatory=\"true\"\n```\n\n**For Important ENVs**:\n\nWhat are the environment variables that this container image defines? \n\n```dockerfile\nLABEL api.ENV.OPENWEATHERMAP_APIKEY=\"\" \\\n      api.ENV.OPENWEATHERMAP_APIKEY.about=\"Access key for OpenWeatherMap. See http://openweathermap.org/appid for details.\" \\\n      api.ENV.OPENWEATHERMAP_APIKEY.mandatory=\"true\"\n```\n\n**For Exposed Ports**:\n\nDo we expose any ports? \n\n```dockerfile\nLABEL api.EXPOSE.1337=\"\" \\\n      api.EXPOSE.1337.scheme=\"tcp\" \\\n\t  api.EXPOSE.1337.protocol=\"http\"\\\n      api.EXPOSE.1337.about=\"The main endpoint of this service.\"\n```\n\n**For resources used by the container image**:\n\nWhat resources are required by my application to run in a smooth and performant manner?\n\n```dockerfile\nLABEL api.RESOURCES.Memory=\"3gb\"\\\n      api.RESOURCES.CPU=\"2\"\n```\n\n**For Important Tags** \n\nWhat are some important tags that I want my Dockerfile to expose?\n\n```dockerfile\nLABEL api.TAGS.go=\"1.9\"\n```\n\n**For Container Tests** \n\nTests help you make sure that your container image conforms with what you actually wants it to do. To this end, we decided to support the [container-structured-test](https://github.com/GoogleCloudPlatform/container-structure-test) style. There are four types that are supported by Dockument:\n\n- **Command Tests:** \"Command tests ensure that certain commands run properly in the target image\".\n\n\n```dockerfile\nLABEL api.TEST.command=\"\"\\\n      api.TEST.command.name=\"go version\"\\\n      api.TEST.command.command=\"go\"\\\n      api.TEST.command.args=\"version\"\\\n      api.TEST.command.expectedOutput=\"go version\"\n```\n\n- **File Existence Tests:** \"File existence tests check to make sure a specific file (or directory) exist within the file system of the image.\"\n\n```dockerfile\nLABEL api.TEST.fileExistence=\"\"\\\n      api.TEST.fileExistence.name=\"Dockumentation Check\"\\\n      api.TEST.fileExistence.path=\"/dockumentation.md\"\\\n      api.TEST.fileExistence.shouldExist=\"true\"\\\n      api.TEST.fileExistence.permissions=\"\"\n```\n\n- **File Content Tests:** \"File content tests open a file on the file system and check its contents.\" \n\n```dockerfile\nLABEL api.TEST.fileContent=\"\"\\\n      api.TEST.fileContent.name=\"Debian Sources\"\\\n      api.TEST.fileContent.path=\"/etc/apt/sources.list\"\\\n      api.TEST.fileContent.expectedContents=\"['.*httpredir\\\\.debian\\\\.org.*']\"\\\n      api.TEST.fileContent.excludedContents=\"['.*gce_debian_mirror.*']\"\n``` \n\n- **Meta data tests**: \"The Metadata test ensures the container is configured correctly\". \n\n```dockerfile\nLABEL api.TEST.metadata=\"\"\\\n      api.TEST.metadata.env=\"GOPATH:/go\"\\\n      api.TEST.metadata.exposedPorts=\"\"\\\n      api.TEST.metadata.volumes=\"\"\\\n      api.TEST.metadata.cmd=\"\"\\\n      api.TEST.metadata.workdir=\"\"\n```\n\n\nFor a complete example, please have a look at [this Dockerfile](https://github.com/zanetworker/dockument/blob/master/examples/Dockerfile) or [this Dockerfile by luebken](https://github.com/luebken/currentweather/blob/master/Dockerfile)\n\n\n## Contributing\n\n\u003c!-- [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) --\u003e\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Authors\n\nSee also the list of [contributors](https://github.com/zanetworker/dockument/graphs/contributors) who participated in this project.\n\n## TODO\n\n[ ] Testing\n\n## License\n\nThis project is licensed under the Apache License - see the [LICENSE](LICENSE) file for details\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanetworker%2Fdockument","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzanetworker%2Fdockument","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanetworker%2Fdockument/lists"}