It seems like there are two ways to add documentation to a docker image:
You can add a readme.md in the root folder (where your docker file is located) and this is meant to be parsed by the dockerhub automated build system.
The second way is by using the manifest
https://docs.docker.com/docker-hub/publish/publish/#prepare-your-image-manifest-materials
But the documentation doesn't really explain well how to annotate the manifest file for an image. Also it looks like the manifest command is considered experimental.
What is the recommended way of documenting a docker image?
Personally i prefer not having to add documentation when the container is being built, i would much rather a file in the source control. However the md file method seems to have minimal support.
Most modern container registries (like Dockerhub, Quay, Harbor) have a webinterface that can render and display documentation in Markdown format. When you do automatic builds on Dockerhub from a Github repo, the git repo's README.md can get automatically synced to the repo on Docker Hub. If you build your images locally (or via a CI runner) and push them to Docker Hub you could also push the README file using the docker-pushrm tool. It also supports other container registries than Dockerhub.
Related
I've managed to create a docker-compose file which runs my application. Now I'm wondering if there's a standard way for distributing this file? I mean, with docker I would distribute the image uploaded to docker-hub built from my Dockerfile, can I also upload docker-compose files to docker-hub?
What would the deployment flow look like here?
You can deploy single images on DockerHub
You can't deploy a docker-compose file to DockerHub
The way that I saw the most is :
Creating a Github repository containing your project (with the
docker-compose file)
Explaining how to create the different images in a Readme.md
Push each images on DockerHub and link your DockerHub images to your
git repositories to allow people to check the whole stack.
I learnt the basics of github and docker and both work well in my environment. On my server, I have project directories, each with a docker-compose.yml to run the necessary containers. These project directories also have the actual source files for that particular app which are mapped to virtual locations inside the containers upon startup.
My question is now- how to create a pro workflow to encapsulate all of this? Should the whole directory (including the docker-compose files) live on github? Thus each time changes are made I push the code to my remote, SSH to the server, pull the latest files and rebuild the container. This rebuilding of course means pulling the required images from dockerhub each time.
Should the whole directory (including the docker-compose files) live on github?
It is best practice to keep all source code including dockerfiles, configuration ... versioned. Thus you should put all the source code, dockerfile, and dockercompose in a git reporitory. This is very common for projects on github that have a docker image.
Thus each time changes are made I push the code to my remote, SSH to the server, pull the latest files and rebuild the container
Ideally this process should be encapsulated in a CI workflow using a tool like Jenkins. You basically push the code to the git repository,
which triggers a jenkins job that compiles the code, builds the image and pushes the image to a docker registry.
This rebuilding of course means pulling the required images from dockerhub each time.
Docker is smart enough to cache the base images that have been previously pulled. Thus it will only pull the base images once on the first build.
Right now I have multiple components of my application in the same folder linked together with a docker-compose
This works really well in development, but when I want to push to production it's kind of fuzzy. If I keep this structure I cannot use only dockerhub to host my images because the docker-compose which links them will be missing. If I use git to pull down my docker-compose, what would be the point of dockerhub? Why not just clone my whole repo and run docker-compose up each time?
I could alternatively store each component separately in separate github repos, pushing them up to dockerhub when pushed to master. Then, simply combine them from the hub with a dockercompose. This seems less than ideal too, since one would have to clone and push to several different repos to make a change which effects the system.
How do you do it?
I have two parts: source code and config files (docker files, docker-compose files...)
I put Dockerfile and docker-compose in a folder with the struct like you and push it to a git repository. For source code (and other data), I have to manage it by hand, with separated git repositories for source code to push and pull each time it needs to update.
Be careful with the production server, just update small part instead of the whole server.
Check out the new (still experimental) docker-app (June 2018)
It will allow you to push your docker-compose to DockerHub, as well as launch your app (through docker-compose) with settings variations between dev and prod.
See example:
You can create an Application Package based on this Compose file:
$ docker-app init --single-file hello
$ ls
docker-compose.yml
hello.dockerapp
The new new file hello.dockerapp contains three YAML documents:
metadatas
the Compose file
settings for your application
See "Sharing your application on the Hub"
You can push any application to the Hub using docker-app push:
$ docker-app push --namespace myHubUser --tag latest
This command will create an image named myHubUser/hello.dockerapp:latest on your local Docker daemon, and push it to the Hub.
I know that Docker hub is there but it allows only for 1 private repository. Can I put these images on Github/Bitbucket?
In general you don't want to use version control on large binary images (like videos or compiled files) as git and such was intended for 'source control', emphasis on the source. Technically, here's nothing preventing you from doing so and putting the docker image files into git (outside the limits of the service you're using).
One major issue you'll have is git/bitubucket have no integration with Docker as neither provide the Docker Registry api needed for a docker host to be able to pull down the images as needed. This means you'll need to manually pull down out of the version control system holding the image files if you want to use it.
If you're going to do that, why not just use S3 or something like that?
If you really want 'version control' on your images (which docker hub does not do...) you'd need to look at something like: https://about.gitlab.com/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/
Finally, docker hub only allows one FREE private repo. You can pay for more.
So the way to go is:
Create a repository on Github or Bitbucket
Commit and push your Dockerfile (with config files if necessary)
Create an automated build on Docker Hub which uses the Github / Bitbucket repo as source.
In case you need it all private you can self-host a git service like Gitlab or GOGS and of course you can also selfhost a docker registry service for the images.
Yes, since Sept. 2020.
See "Introducing GitHub Container Registry" from Kayla Ngan:
Since releasing GitHub Packages last year (May 2019), hundreds of millions of packages have been downloaded from GitHub, with Docker as the second most popular ecosystem in Packages behind npm.
Available today as a public beta, GitHub Container Registry improves how we handle containers within GitHub Packages.
With the new capabilities introduced today, you can better enforce access policies, encourage usage of a standard base image, and promote innersourcing through easier sharing across the organization.
Our users have asked for anonymous access for public container images, similar to how we enable anonymous access to public repositories of source code today.
Anonymous access is available with GitHub Container Registry today, and we’ve gotten things started today by publishing a public image of our own super-linter.
GitHub Container Registry is free for public images.
With GitHub Actions, publishing to GitHub Container Registry is easy. Actions automatically suggests workflows based for you based on your work, and we’ve updated the “Publish Docker Container” workflow template to make publishing straightforward.
GitHub is in the process of releasing something similar to ECR or Docker Hub. At the time of writing this, it's in Alpha phase and you can request access.
From GitHub:
"GitHub Package Registry is a software package hosting service, similar to npmjs.org, rubygems.org, or hub.docker.com, that allows you to host your packages and code in one place. You can host software packages privately or publicly and use them as dependencies in your projects."
https://help.github.com/en/articles/about-github-package-registry
I guess you are saying about docker images. You can setup your own private registry which will contain the docker images. If you are not pushing only dockerfiles, but are interested in pushing the whole image, then pushing the images as a whole to github is a very bad idea. Consider a case you have 600 MB of docker image, pushing it to github is like putting 600 MB of data to a github repo, and if you keep on pushing more images there, it will get terribly bad.
Also, docker registry does the intelligent mapping of storing only a single copy of a layer (this layer can be referenced by multiple images). If you use github, you are not going to use this use-case. You will end up storing multiple copies of large files which is really really bad.
I would definitely suggest you to go with a private docker registry rather than going with github.
If there is a real need of putting docker image to github/bitbucket you can try to save it into archive (by using https://docs.docker.com/engine/reference/commandline/save/) and commit/push it to your repository.
I'm new to docker and I wonder why there is no command to fetch AUTOMATED BUILD-repo's Dockerfile to build image locally from it (can be convenient some times I guess, instead of opening browser, peeking for github reference on repo's page and then using git to clone)
I have created dockerfileview to fetch Dockerfile from Docker Hub.
https://github.com/remore/dockerfileview
The automated build normally has a githubrepo behind it and links to the original repository in the build details section under the Source Repository heading. Which automated build are you looking for the source file for?
If you would like to search for images from the command line you can run docker search TERM to find images (but not their docker files). You can also use docker history to give a rough approximation of the commands that went in the docker file.
e.g.