Source repo for Docker's Documentation
Branch: master
Clone or download
bermudezmt Merge pull request #8307 from ollypom/offlineimageload
EE Offline Bundle Load Command now works on Windows
Latest commit dca9a45 Feb 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Rename .github/CONTRIBUTING.md to CONTRIBUTING.md (#1416) Feb 18, 2017
_data Update toc.yaml Feb 15, 2019
_includes Use consistent formatting for notes Feb 8, 2019
_layouts Rename / remove edge-related variables Jan 14, 2019
_samples Rename Docker Store and Docker Cloud - WIP Oct 4, 2018
_scripts Rename / remove edge-related variables Jan 14, 2019
_scss Merge pull request #7492 from artywhite/fix-navsidebar-hover-cursor-p… Jan 5, 2019
compose Merge pull request #8198 from thaJeztah/note_picking Feb 12, 2019
config Improve `fluentd-async-connect` option Feb 18, 2019
cs-engine Various copyedits to reduce future tense, wordiness, and use of 'plea… Jan 26, 2018
css Make archive easier (#5231) Jan 30, 2018
datacenter Merge pull request #8223 from docker/ucp-install Feb 15, 2019
develop Typo: "use HTTP API" => "use the HTTP API" Feb 15, 2019
docker-for-aws Merge pull request #7664 from docker/editions-18.06.1-CE Dec 26, 2018
docker-for-azure ordered Feb 17, 2019
docker-for-mac Fix broken preferences link Feb 15, 2019
docker-for-windows Docker Desktop for Windows - fix broken download link for the 2.0.0.3… Feb 18, 2019
docker-hub Use consistent formatting for notes Feb 8, 2019
docker-id Re-write Orgs & Webhooks docs Nov 22, 2018
edge Rename / remove edge-related variables Jan 14, 2019
ee Made the Load command compatible with Windows and Linux Feb 19, 2019
engine Merge pull request #8295 from docker/release-notes-eng-2019 Feb 19, 2019
favicons Use new favicon Mar 2, 2017
fonts Convert TOML to YAML, tweaks to work with Jekyll Sep 30, 2016
get-started Update part3.md Feb 14, 2019
hackathon Move /engine/installation to /install (#5651) Jan 26, 2018
images Added 404 from home page, fixed text. Jan 8, 2019
install Add 304 redirect for old installation page Feb 15, 2019
js Merge branch 'master' into name-change-for-Docker-Desktop Jan 14, 2019
kitematic Update userguide.md Jan 11, 2019
machine Use consistent formatting for notes Feb 8, 2019
network Update overlay.md Feb 12, 2019
notary Rename official repos to official images Nov 21, 2018
opensource Add redirects for old opensource pages (#5946) Feb 7, 2018
reference Merge pull request #8223 from docker/ucp-install Feb 15, 2019
registry Update help.md Feb 15, 2019
release-notes Use consistent formatting for notes Feb 8, 2019
samples Update sample image table links and overview Jan 9, 2019
storage Use consistent formatting for notes Feb 8, 2019
swarm Move externally hosted images to the repo, and update image links Feb 6, 2019
tests Spelling revision Sep 23, 2018
toolbox Update toolbox_install_mac.md Jan 11, 2019
.NOT_EDITED_HERE.yaml Pull distribution reference docs from upstream Nov 28, 2016
.dockerignore Update .dockerignore Apr 20, 2017
.eslintignore Initial commit -f https://github.com/docker/mercury-ui Sep 28, 2016
.gitignore Navigation under "Reference" and "Manuals," Registry warning, "Latest… Dec 8, 2017
.gitmodules Update .gitmodules Nov 16, 2018
.nojekyll Take down docker.github.io Apr 12, 2018
.ruby-version Create .ruby-version Nov 5, 2016
404.html Make changes based on feedback Apr 26, 2018
404.md Update 404.md Jan 8, 2019
CONTRIBUTING.md Remove link to non-existent style guide Nov 12, 2018
Dockerfile Update Dockerfile Jan 9, 2019
Dockerfile.archive Use multistage build for master (#5369) Dec 27, 2017
Gemfile Gemfile: bump gh-pages to v177 Mar 13, 2018
Jenkinsfile add new Jenkinsfile Jan 23, 2019
LICENSE Content rendering fixes Sep 30, 2016
README.md Update README.md Feb 13, 2019
_config.yml Updated Win Engine Ver to 18.09.2 Feb 12, 2019
_config_authoring.yml Sync config-authoring.yml Jan 15, 2019
components.md Spelling mistakes (#2970) Apr 20, 2017
docker-compose.yml remind compose file how to build May 3, 2018
docker-for-ibm-cloud.md Add redirect from v17.12 version of page since the product has been E… Feb 7, 2019
docsarchive.md Speed up site rendering for authors (#5241) Dec 20, 2017
favicon.ico Use new favicon Mar 2, 2017
glossary.md Update glossary.md (#4707) Sep 26, 2017
googlecbe7fee896be512c.html Website verification Oct 10, 2016
index.html Make changes based on feedback Apr 26, 2018
index.md Update index.md Jan 11, 2019
reference.md Rename Docker Store and Docker Cloud - WIP Oct 4, 2018
robots.txt Updating config, docsarchive, robots.txt files Sep 11, 2018
search.md Fix search page to not render raw HTML (#6038) Feb 21, 2018
test.md Added PowerShell sample Feb 6, 2019
thank-you-subscribing-docker-weekly.md Revert "Adding period to confirmation message" Aug 30, 2018

README.md

Docs @ Docker

Welcome to the repo for our documentation. This is the source for https://docs.docker.com/.

Feel free to send us pull requests and file issues. Our docs are completely open source and we deeply appreciate contributions from our community!

Providing feedback

We really want your feedback, and we've made it easy. You can edit a page or request changes in the right column of every page on docs.docker.com. You can also rate each page by clicking a link at the footer.

Only file issues about the documentation in this repository. One way to think about this is that you should file a bug here if your issue is that you don't see something that should be in the docs, or you see something incorrect or confusing in the docs.

  • If your problem is a general question about how to configure or use Docker, ask in https://forums.docker.com instead.

  • If you have an idea for a new feature or behavior change in a specific aspect of Docker, or have found a bug in part of Docker, file that issue in the project's code repository.

Contributing

We value your documentation contributions, and we want to make it as easy as possible to work in this repository. One of the first things to decide is which branch to base your work on. If you get confused, just ask and we will help. If a reviewer realizes you have based your work on the wrong branch, we'll let you know so that you can rebase it.

Note: To contribute code to Docker projects, see the Contribution guidelines.

Files not edited here

Files and directories listed in the path: keys in .NOT_EDITED_HERE.yaml are maintained in other repositories and should not be edited in this one. Pull requests against these files will be rejected. Make your edits to the files in the repository and path in the source: key in the YAML file.

Overall doc improvements

Most commits will be made against the master branch. This include:

  • Conceptual and task-based information not specific to new features
  • Restructuring / rewriting
  • Doc bug fixing
  • Typos and grammar errors

One quirk of this project is that the master branch is where the live docs are published from, so upcoming features can't be documented there. See Specific new features for a project for how to document upcoming features. These feature branches will be periodically merged with master, so don't worry about fixing typos and documentation bugs there.

Do you enjoy creating graphics? Good graphics are key to great documentation, and we especially value contributions in this area.

Specific new features for a project

Our docs cover many projects which release at different times. If, and only if, your pull request relates to a currently unreleased feature of a project, base your work on that project's vnext branch. These branches were created by cloning master and then importing a project's master branch's docs into it (at the time of the migration), in a way that preserved the commit history. When a project has a release, its vnext branch will be merged into master and your work will be visible on https://docs.docker.com/.

The following vnext branches currently exist:

Per-PR staging on GitHub

For every PR against master and all the long-lived branches, a staged version of the site is built using Netlify. If the site builds, you will see deploy/netlify — Deploy preview ready. Otherwise, you will see an error. Click Details to review the staged site or the errors that prevented it from building. Review the staged site and amend your commit if necessary. Reviewers will also check the staged site before merging the PR, to protect the integrity of https://docs.docker.com/.

Staging the docs

You have two options:

  1. On your local machine, clone this repo and run our staging container:

    git clone --recursive https://github.com/docker/docker.github.io.git
    cd docker.github.io
    docker-compose up

    If you haven't got Docker Compose installed, follow these installation instructions.

    The container runs in the background and incrementally rebuilds the site each time a file changes. You can keep your browser open to http://localhost:4000/ and refresh to see your changes. The container runs in the foreground, but you can use CTRL+C to get the command prompt back. To stop the container, issue the following command:

    docker-compose down
  2. Install Jekyll and GitHub Pages on your local machine.

    a. Clone this repo by running:

    git clone --recursive https://github.com/docker/docker.github.io.git

    b. Install Ruby 2.3 or later as described in Installing Ruby.

    c. Install Bundler:

    gem install bundler

    d. If you use Ubuntu, install packages required for the Nokogiri HTML parser:

    sudo apt-get install ruby-dev zlib1g-dev liblzma-dev

    e. Install Jekyll and other required dependencies:

    bundle install

    Note: You may need to install some packages manually.

    f. Change the directory to docker.github.io.

    g. Use the jekyll serve command to continuously build the HTML output.

    The jekyll serve process runs in the foreground, and starts a web server running on http://localhost:4000/ by default. To stop it, use CTRL+C. You can continue working in a second terminal and Jekyll will rebuild the website incrementally. Refresh the browser to preview your changes.

Read these docs offline

To read the docs offline, you can use either a standalone container or a swarm service. To see all available tags, go to Docker Hub.

The following examples use the latest tag:

  • Run a single container:

    docker run  -it -p 4000:4000 docs/docker.github.io:latest
  • Run a swarm service:

    docker service create -p 4000:4000 --name localdocs --replicas 1 docs/docker.github.io:latest

    This example uses only a single replica, but you could run as many replicas as you'd like.

Either way, you can now access the docs at port 4000 on your Docker host.

Important files

  • /_data/toc.yaml defines the left-hand navigation for the docs
  • /js/menu.js defines most of the docs-specific JS such as TOC generation and menu syncing
  • /css/style.scss defines the docs-specific style rules
  • /_layouts/docs.html is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content

Relative linking for GitHub viewing

Feel free to link to ../foo.md so that the docs are readable in GitHub, but keep in mind that Jekyll templating notation {% such as this %} will render in raw text and not be processed. In general it's best to assume the docs are being read directly on https://docs.docker.com/.

Testing changes and practical guidance

If you want to test a style change, or if you want to see how to achieve a particular outcome with Markdown, Bootstrap, JQuery, or something else, have a look at test.md (which renders in the site at /test/).

Per-page front-matter

The front-matter of a given page is in a section at the top of the Markdown file that starts and ends with three hyphens. It includes YAML content. The following keys are supported. The title, description, and keywords are required.

Key Required Description
title yes The page title. This is added to the HTML output as a <h1> level header.
description yes A sentence that describes the page contents. This is added to the HTML metadata.
keywords yes A comma-separated list of keywords. These are added to the HTML metadata.
redirect_from no A YAML list of pages which should redirect to THIS page. At build time, each page listed here is created as a HTML stub containing a 302 redirect to this page.
notoc no Either true or false. If true, no in-page TOC is generated for the HTML output of this page. Defaults to false. Appropriate for some landing pages that have no in-page headings.
toc_min no Ignored if notoc is set to true. The minimum heading level included in the in-page TOC. Defaults to 2, to show <h2> headings as the minimum.
toc_max no Ignored if notoc is set to false. The maximum heading level included in the in-page TOC. Defaults to 3, to show <h3> headings. Set to the same as toc_min to only show toc_min level of headings.
tree no Either true or false. Set to false to disable the left-hand site-wide navigation for this page. Appropriate for some pages like the search page or the 404 page.
no_ratings no Either true or false. Set to true to disable the page-ratings applet for this page. Defaults to false.

The following is an example of valid (but contrived) page metadata. The order of the metadata elements in the front-matter is not important.

---
description: Instructions for installing Docker on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
redirect_from:
- /engine/installation/ubuntulinux/
- /installation/ubuntulinux/
- /engine/installation/linux/ubuntulinux/
title: Get Docker for Ubuntu
toc_min: 1
toc_max: 6
tree: false
no_ratings: true
---

Creating tabs

The use of tabs, as on pages like https://docs.docker.com/engine/api/, requires the use of HTML. The tabs use Bootstrap CSS/JS, so refer to those docs for more advanced usage. For a basic horizontal tab set, copy/paste starting from this code and implement from there. Keep an eye on those href="#id" and id="id" references as you rename, add, and remove tabs.

<ul class="nav nav-tabs">
  <li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
  <li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
</ul>
<div class="tab-content">
  <div id="tab1" class="tab-pane fade in active">TAB 1 CONTENT</div>
  <div id="tab2" class="tab-pane fade">TAB 2 CONTENT</div>
</div>

For more info and a few more permutations, see test.md.

Running in-page Javascript

If you need to run custom Javascript within a page, and it depends upon JQuery or Bootstrap, make sure the <script> tags are at the very end of the page, after all the content. Otherwise the script may try to run before JQuery and Bootstrap JS are loaded.

Note: In general, this is a bad idea.

Images

Don't forget to remove images that are no longer used. Keep the images sorted in the local images/ directory, with names that naturally group related images together in alphabetical order. For instance prefer settings-file-share.png and settings-proxies.png to file-share-settings.png and proxies-settings.png. You may also use numbers, especially in the case of a sequence, e.g., run-only-the-images-you-trust-1.svg run-only-the-images-you-trust-2.png run-only-the-images-you-trust-3.png.

When applicable, capture windows rather than rectangular regions. This eliminates unpleasant background and saves the editors the need to crop.

On Mac, capture windows without shadows. To this end, once you pressed Command-Shift-4, press Option while clicking on the window. To disable shadows once for all, run:

$ defaults write com.apple.screencapture disable-shadow -bool TRUE
$ killall SystemUIServer  # restart it.

You can restore shadows later with -bool FALSE.

In order to keep the Git repository light, please compress the images (losslessly). On Mac you may use (ImageOptim)[https://imageoptim.com] for instance. Be sure to compress the images before adding them to the repository, doing it afterwards actually worsens the impact on the Git repo (but still optimizes the bandwidth during browsing).

Beta content disclaimer

> BETA DISCLAIMER
>
> This is beta content. It is not yet complete and should be considered a work in progress. This content is subject to change without notice.

Accessing unsupported archived documentation

Supported documentation includes the current version plus the previous five versions.

If you are using a version of the documentation that is no longer supported, which means that the version number is not listed in the site dropdown list, you can still access that documentation in the following ways:

 docker run  -it -p 4000:4000 docs/docker.github.io:v1.9

Building archives and the live published docs

All the images described below are automatically built using Docker Hub. To build the site manually, from scratch, including all utility and archive images, see the README in the publish-tools branch.

  • Some utility images are built from Dockerfiles in the publish-tools branch. See its README for details.
  • Each archive branch automatically builds an image tagged docs/docker.github.io:v<VERSION> when a change is merged into that branch.
  • The master branch has a Dockerfile which uses the static HTML from each archive image, in combination with the Markdown files in master and some upstream resources which are fetched at build-time, to create the full site at https://docs.docker.com/. All of the long-running branches, such as vnext-engine, vnext-compose, etc, use the same logic.

Creating a new archive

When a new Docker CE Stable version is released, the previous state of master is archived into a version-specific branch like v17.09, by doing the following:

  1. Create branch based off the commit hash before the new version was released.

    $ git checkout <HASH>
    $ git checkout -b v17.09
  2. Run the _scripts/fetch-upstream-resources.sh script. This puts static copies of the files in place that the master build typically fetches each build.

    $ _scripts/fetch-upstream/resources.sh
  3. Overwrite the Dockerfile with the Dockerfile.archive (use cp rather than mv so you don't inadvertently remove either file). Edit the resulting Dockerfile and set the VER build argument to the appropriate value, like v17.09.

    $ mv Dockerfile.archive Dockerfile
    $ vi Dockerfile
    
      < edit the variable and save >
  4. Do git status and add all changes, being careful not to add anything extra by accident. Commit your work.

    $ git status
    $ git add <filename>
    $ git add <filename> (etc etc etc)
    $ git commit -m "Creating archive for 17.09 docs"
  5. Make sure the archive builds.

    $ docker build -t docker build -t docs/docker.github.io:v17.09 .
    $ docker run --rm -it -p 4000:4000 docs/docker.github.io:v17.09

    After the docker run command, browse to http://localhost:4000/ and verify that the archive is self-browseable.

  6. Push the branch to the upstream repository. Do not create a pull request as there is no reference branch to compare against.

    $ git push upstream v17.09

Copyright and license

Code and documentation copyright 2017 Docker, inc, released under the Apache 2.0 license.