Merge pull request #23492 from londoncalling/docs-surface-tutorials-v1.12

surfacing Learn by example topics to top level of Docker Engine docs

docs/examples/index.md

@@ -19,4 +19,4 @@ This section contains the following:
 * [Dockerizing a CouchDB service](couchdb_data_volumes.md)         
 * [Dockerizing a Redis service](running_redis_service.md)
 * [Dockerizing an apt-cacher-ng service](apt-cacher-ng.md)
-* [Dockerizing applications: A 'Hello world'](../userguide/containers/dockerizing.md)
+* [Dockerizing applications: A 'Hello world'](../tutorials/dockerizing.md)

docs/reference/builder.md

@@ -100,7 +100,7 @@ the `Using cache` message in the console output.
     Successfully built 7ea8aef582cc
 
 When you're done with your build, you're ready to look into [*Pushing a
-repository to its registry*](../userguide/containers/dockerrepos.md#contributing-to-docker-hub).
+repository to its registry*](../tutorials/dockerrepos.md#contributing-to-docker-hub).
 
 ## Format
 
@@ -474,7 +474,7 @@ Or
 The `FROM` instruction sets the [*Base Image*](glossary.md#base-image)
 for subsequent instructions. As such, a valid `Dockerfile` must have `FROM` as
 its first instruction. The image can be any valid image – it is especially easy
-to start by **pulling an image** from the [*Public Repositories*](../userguide/containers/dockerrepos.md).
+to start by **pulling an image** from the [*Public Repositories*](../tutorials/dockerrepos.md).
 
 - `FROM` must be the first non-comment instruction in the `Dockerfile`.
 
@@ -1171,7 +1171,7 @@ containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
 /var/db`. For more information/examples and mounting instructions via the
 Docker client, refer to
-[*Share Directories via Volumes*](../userguide/containers/dockervolumes.md#mount-a-host-directory-as-a-data-volume)
+[*Share Directories via Volumes*](../tutorials/dockervolumes.md#mount-a-host-directory-as-a-data-volume)
 documentation.
 
 The `docker run` command initializes the newly created volume with any data

docs/reference/commandline/export.md

@@ -23,7 +23,7 @@ the container, `docker export` will export the contents of the *underlying*
 directory, not the contents of the volume.
 
 Refer to [Backup, restore, or migrate data
-volumes](../../userguide/containers/dockervolumes.md#backup-restore-or-migrate-data-volumes) in
+volumes](../../tutorials/dockervolumes.md#backup-restore-or-migrate-data-volumes) in
 the user guide for examples on exporting data in a volume.
 
 ## Examples

docs/reference/commandline/search.md

@@ -24,7 +24,7 @@ parent = "smn_cli"
 
 Search [Docker Hub](https://hub.docker.com) for images
 
-See [*Find Public Images on Docker Hub*](../../userguide/containers/dockerrepos.md#searching-for-images) for
+See [*Find Public Images on Docker Hub*](../../tutorials/dockerrepos.md#searching-for-images) for
 more details on finding shared images from the command line.
 
 > **Note:**
@@ -124,5 +124,3 @@ This example displays images with a name containing 'busybox', at least
     NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
     progrium/busybox                                                     50                   [OK]
     radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
-
-

docs/reference/commandline/tag.md

@@ -19,10 +19,10 @@ parent = "smn_cli"
 An image name is made up of slash-separated name components, optionally prefixed
 by a registry hostname. The hostname must comply with standard DNS rules, but
 may not contain underscores. If a hostname is present, it may optionally be
-followed by a port number in the format `:8080`. If not present, the command 
-uses Docker's public registry located at `registry-1.docker.io` by default. Name 
-components may contain lowercase characters, digits and separators. A separator 
-is defined as a period, one or two underscores, or one or more dashes. A name 
+followed by a port number in the format `:8080`. If not present, the command
+uses Docker's public registry located at `registry-1.docker.io` by default. Name
+components may contain lowercase characters, digits and separators. A separator
+is defined as a period, one or two underscores, or one or more dashes. A name
 component may not start or end with a separator.
 
 A tag name may contain lowercase and uppercase characters, digits, underscores,
@@ -30,20 +30,20 @@ periods and dashes. A tag name may not start with a period or a dash and may
 contain a maximum of 128 characters.
 
 You can group your images together using names and tags, and then upload them
-to [*Share Images via Repositories*](../../userguide/containers/dockerrepos.md#contributing-to-docker-hub).
+to [*Share Images via Repositories*](../../tutorials/dockerrepos.md#contributing-to-docker-hub).
 
 # Examples
 
 ## Tagging an image referenced by ID
 
-To tag a local image with ID "0e5574283393" into the "fedora" repository with 
+To tag a local image with ID "0e5574283393" into the "fedora" repository with
 "version1.0":
 
     docker tag 0e5574283393 fedora/httpd:version1.0
 
 ## Tagging an image referenced by Name
 
-To tag a local image with name "httpd" into the "fedora" repository with 
+To tag a local image with name "httpd" into the "fedora" repository with
 "version1.0":
 
     docker tag httpd fedora/httpd:version1.0

docs/reference/commandline/volume_create.md

@@ -73,4 +73,4 @@ $ docker volume create --driver local --opt type=btrfs --opt device=/dev/sda2
 * [volume inspect](volume_inspect.md)
 * [volume ls](volume_ls.md)
 * [volume rm](volume_rm.md)
-* [Understand Data Volumes](../../userguide/containers/dockervolumes.md)
+* [Understand Data Volumes](../../tutorials/dockervolumes.md)

docs/reference/commandline/volume_inspect.md

@@ -45,4 +45,4 @@ Example output:
 * [volume create](volume_create.md)
 * [volume ls](volume_ls.md)
 * [volume rm](volume_rm.md)
-* [Understand Data Volumes](../../userguide/containers/dockervolumes.md)
+* [Understand Data Volumes](../../tutorials/dockervolumes.md)

docs/reference/commandline/volume_ls.md

@@ -81,4 +81,4 @@ The following filter matches all volumes with a name containing the `rose` strin
 * [volume create](volume_create.md)
 * [volume inspect](volume_inspect.md)
 * [volume rm](volume_rm.md)
-* [Understand Data Volumes](../../userguide/containers/dockervolumes.md)
+* [Understand Data Volumes](../../tutorials/dockervolumes.md)

docs/reference/commandline/volume_rm.md

@@ -26,4 +26,4 @@ Removes one or more volumes. You cannot remove a volume that is in use by a cont
 * [volume create](volume_create.md)
 * [volume inspect](volume_inspect.md)
 * [volume ls](volume_ls.md)
-* [Understand Data Volumes](../../userguide/containers/dockervolumes.md)
+* [Understand Data Volumes](../../tutorials/dockervolumes.md)

docs/reference/run.md

@@ -1078,7 +1078,7 @@ Both flags take limits in the `<device-path>:<limit>` format. Both read and
 write rates must be a positive integer.
 
 ## Additional groups
-    --group-add: Add additional groups to run as 
+    --group-add: Add additional groups to run as
 
 By default, the docker container process runs with the supplementary groups looked
 up for the specified user. If one wants to add more to that list of groups, then
@@ -1502,8 +1502,8 @@ The example below mounts an empty tmpfs into the container with the `rw`,
 > a volume.
 
 The volumes commands are complex enough to have their own documentation
-in section [*Managing data in
-containers*](../userguide/containers/dockervolumes.md). A developer can define
+in section [*Manage data in
+containers*](../tutorials/dockervolumes.md). A developer can define
 one or more `VOLUME`'s associated with an image, but only the operator
 can give access from one container to another (or from a container to a
 volume mounted on the host).
@@ -1532,7 +1532,7 @@ Dockerfile `USER` instruction. When starting a container, the operator can overr
 the `USER` instruction by passing the `-u` option.
 
     -u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command.
- 
+
     The followings examples are all valid:
     --user=[ user | user:group | uid | uid:gid | user:gid | uid:group ]
 

docs/userguide/containers/dockerimages.md → docs/tutorials/dockerimages.md

@@ -1,6 +1,9 @@
 <!--[metadata]>
 +++
-aliases = ["/engine/userguide/dockerimages/"]
+aliases = [
+"/engine/userguide/containers/dockerimages/",
+"/engine/userguide/dockerimages/"
+]
 title = "Build your own images"
 description = "How to work with Docker images."
 keywords = ["documentation, docs, the docker guide, docker guide, docker, docker platform, docker.io, Docker images, Docker image, image management, Docker repos, Docker repositories, docker, docker tag, docker tags, Docker Hub,  collaboration"]
@@ -472,10 +475,10 @@ You can then create a container from our new image.
 > This is just a brief introduction to creating images. We've
 > skipped a whole bunch of other instructions that you can use. We'll see more of
 > those instructions in later sections of the Guide or you can refer to the
-> [`Dockerfile`](../../reference/builder.md) reference for a
+> [`Dockerfile`](../reference/builder.md) reference for a
 > detailed description and examples of every instruction.
 > To help you write a clear, readable, maintainable `Dockerfile`, we've also
-> written a [`Dockerfile` Best Practices guide](../eng-image/dockerfile_best-practices.md).
+> written a [`Dockerfile` Best Practices guide](../userguide/eng-image/dockerfile_best-practices.md).
 
 
 ## Setting tags on an image

docs/userguide/containers/dockerizing.md → docs/tutorials/dockerizing.md

@@ -1,11 +1,14 @@
 <!--[metadata]>
 +++
-aliases = ["/engine/userguide/dockerizing/"]
+aliases = [
+"/engine/userguide/containers/dockerizing/",
+"/engine/userguide/dockerizing/"
+]
 title = "Hello world in a container"
 description = "A simple 'Hello world' exercise that introduced you to Docker."
 keywords = ["docker guide, docker, docker platform, how to, dockerize, dockerizing apps, dockerizing applications, container,  containers"]
 [menu.main]
-parent="engine_learn"
+parent = "engine_learn"
 weight=-6
 +++
 <![end-metadata]-->

docs/userguide/containers/dockerrepos.md → docs/tutorials/dockerrepos.md

@@ -1,6 +1,9 @@
 <!--[metadata]>
 +++
-aliases = ["/engine/userguide/dockerrepos/"]
+aliases = [
+"/engine/userguide/containers/dockerrepos/",
+"/engine/userguide/dockerrepos/"
+]
 title = "Store images on Docker Hub"
 description = "Learn how to use the Docker Hub to manage Docker images and work flow"
 keywords = ["repo, Docker Hub, Docker Hub, registry, index, repositories, usage, pull image, push image, image,  documentation"]
@@ -42,7 +45,7 @@ $ docker login
 The `login` command stores your Docker ID authentication credentials in the
 `$HOME/.docker/config.json` (Bash notation). For Windows `cmd` users the
 notation for this file is `%HOME%\.docker\config.json` ; for PowerShell users
-the notation is `$env:Home\.docker\config.json`. 
+the notation is `$env:Home\.docker\config.json`.
 
 Once you have logged in from the command line, you can `commit` and `push`
 Engine subcommands to interact with your repos on Docker Hub.

docs/userguide/containers/dockervolumes.md → docs/tutorials/dockervolumes.md

@@ -1,6 +1,9 @@
 <!--[metadata]>
 +++
-aliases = ["/engine/userguide/dockervolumes/"]
+aliases = [
+"/engine/userguide/containers/dockervolumes/",
+"/engine/userguide/dockervolumes/"
+]
 title = "Manage data in containers"
 description = "How to manage data inside your Docker containers."
 keywords = ["Examples, Usage, volume, docker, documentation, user guide, data,  volumes"]
@@ -12,9 +15,9 @@ parent = "engine_learn"
 # Manage data in containers
 
 So far you've been introduced to some [basic Docker
-concepts](../containers/usingdocker.md), seen how to work with [Docker
-images](../containers/dockerimages.md) as well as learned about [networking and
-links between containers](../networking/default_network/dockerlinks.md). In this
+concepts](usingdocker.md), seen how to work with [Docker
+images](dockerimages.md) as well as learned about [networking and
+links between containers](../userguide/networking/default_network/dockerlinks.md). In this
 section you're going to learn how you can manage data inside and between your
 Docker containers.
 
@@ -27,7 +30,7 @@ Docker Engine.
 ## Data volumes
 
 A *data volume* is a specially-designated directory within one or more
-containers that bypasses the [*Union File System*](../../reference/glossary.md#union-file-system). Data volumes provide several useful features for persistent or shared data:
+containers that bypasses the [*Union File System*](../reference/glossary.md#union-file-system). Data volumes provide several useful features for persistent or shared data:
 
 - Volumes are initialized when a container is created. If the container's
   base image contains data at the specified mount point, that existing data is
@@ -170,7 +173,7 @@ user with access to host and its mounted directory.
 ### Mount a shared-storage volume as a data volume
 
 In addition to mounting a host directory in your container, some Docker
-[volume plugins](../../extend/plugins_volume.md) allow you to
+[volume plugins](../extend/plugins_volume.md) allow you to
 provision and mount shared storage, such as iSCSI, NFS, or FC.
 
 A benefit of using shared volumes is that they are host-independent. This
@@ -207,7 +210,7 @@ $ docker run -d -P \
 ```
 
 A list of available plugins, including volume plugins, is available
-[here](../../extend/plugins.md).
+[here](../extend/plugins.md).
 
 ### Volume labels
 
@@ -278,7 +281,7 @@ from the `dbstore` container are visible.
 
 You can use multiple `--volumes-from` parameters to combine data volumes from
 several containers. To find detailed information about `--volumes-from` see the
-[Mount volumes from container](../../reference/commandline/run.md#mount-volumes-from-container-volumes-from)
+[Mount volumes from container](../reference/commandline/run.md#mount-volumes-from-container-volumes-from)
 in the `run` command reference.
 
 You can also extend the chain by mounting the volume that came from the
@@ -369,4 +372,4 @@ combine Docker with the services available on
 [Docker Hub](https://hub.docker.com) including Automated Builds and private
 repositories.
 
-Go to [Working with Docker Hub](../containers/dockerrepos.md).
+Go to [Store images in Docker Hub](dockerrepos.md).

docs/userguide/containers/index.md → docs/tutorials/index.md

@@ -1,11 +1,15 @@
 <!--[metadata]>
 +++
+aliases = [
+"/engine/userguide/containers/",
+]
 title = "Learn by example"
 description = "Explains how to work with containers"
 keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home,  intro"]
 [menu.main]
 identifier="engine_learn"
-parent = "engine_guide"
+parent = "engine_use"
+weight="-80"
 +++
 <![end-metadata]-->
 

docs/userguide/containers/networkingcontainers.md → docs/tutorials/networkingcontainers.md

@@ -1,6 +1,9 @@
 <!--[metadata]>
 +++
-aliases = ["/engine/userguide/networkigncontainers/"]
+aliases = [
+"/engine/userguide/containers/networkigncontainers/",
+"/engine/userguide/networkigncontainers/"
+]
 title = "Network containers"
 description = "How to network Docker containers."
 keywords = ["Examples, Usage, volume, docker, documentation, user guide, data,  volumes"]

docs/userguide/containers/usingdocker.md → docs/tutorials/usingdocker.md

@@ -1,10 +1,13 @@
 <!--[metadata]>
 +++
+aliases = [
+"/engine/userguide/containers/usingdocker/",
+]
 title = "Run a simple application"
 description = "Learn how to manage and operate Docker containers."
 keywords = ["docker, the docker guide, documentation, docker.io, monitoring containers, docker top, docker inspect, docker port, ports, docker logs, log,  Logs"]
 [menu.main]
-parent="engine_learn"
+parent = "engine_learn"
 weight=-5
 +++
 <![end-metadata]-->
@@ -76,7 +79,7 @@ To see usage for a specific command, specify the command with the `--help` flag:
 
 > **Note:**
 > For further details and examples of each command, see the
-> [command reference](../../reference/commandline/cli.md) in this guide.
+> [command reference](../reference/commandline/cli.md) in this guide.
 
 ## Running a web application in Docker
 
@@ -104,8 +107,8 @@ Lastly, you've specified a command for our container to run: `python app.py`. Th
 
 > **Note:**
 > You can see more detail on the `docker run` command in the [command
-> reference](../../reference/commandline/run.md) and the [Docker Run
-> Reference](../../reference/run.md).
+> reference](../reference/commandline/run.md) and the [Docker Run
+> Reference](../reference/run.md).
 
 ## Viewing our web application container
 

docs/userguide/index.md

@@ -6,7 +6,7 @@ keywords = ["engine, introduction, documentation, about, technology, docker, use
 [menu.main]
 parent="engine_use"
 identifier = "engine_guide"
-weight="-80"
+weight="-79"
 +++
 <![end-metadata]-->
 
@@ -18,12 +18,12 @@ This guide helps users learn how to use Docker Engine.
 
 ## Learn by example
 
-- [Hello world in a container](containers/dockerizing.md)
-- [Build your own images](containers/dockerimages.md)
-- [Network containers](containers/networkingcontainers.md)
-- [Run a simple application](containers/usingdocker.md)
-- [Manage data in containers](containers/dockervolumes.md)
-- [Store images on Docker Hub](containers/dockerrepos.md)
+- [Hello world in a container](../tutorials/dockerizing.md)
+- [Build your own images](../tutorials/dockerimages.md)
+- [Network containers](../tutorials/networkingcontainers.md)
+- [Run a simple application](../tutorials/usingdocker.md)
+- [Manage data in containers](../tutorials/dockervolumes.md)
+- [Store images on Docker Hub](../tutorials/dockerrepos.md)
 
 ## Work with images
 

docs/userguide/intro.md

@@ -28,7 +28,7 @@ This guide is broken into major sections that take you through learning the basi
 Docker Engine offers a containerization platform to power your applications. To
 learn how to Dockerize applications and run them:
 
-Go to [Dockerizing Applications](containers/dockerizing.md).
+Go to [Dockerizing Applications](../tutorials/dockerizing.md).
 
 
 ## Working with containers
@@ -38,7 +38,7 @@ Go to [Dockerizing Applications](containers/dockerizing.md).
 Once you get a grip on running your applications in Docker containers, you'll learn how to manage those containers. To find out
 about how to inspect, monitor and manage containers:
 
-Go to [Working with Containers](containers/usingdocker.md).
+Go to [Working with Containers](../tutorials/usingdocker.md).
 
 ## Working with Docker images
 
@@ -47,7 +47,7 @@ Go to [Working with Containers](containers/usingdocker.md).
 Once you've learnt how to use Docker it's time to take the next step and
 learn how to build your own application images with Docker.
 
-Go to [Working with Docker Images](containers/dockerimages.md).
+Go to [Working with Docker Images](../tutorials/dockerimages.md).
 
 ## Networking containers
 
@@ -55,14 +55,14 @@ Until now we've seen how to build individual applications inside Docker
 containers. Now learn how to build whole application stacks with Docker
 networking.
 
-Go to [Networking Containers](containers/networkingcontainers.md).
+Go to [Networking Containers](../tutorials/networkingcontainers.md).
 
 ## Managing data in containers
 
 Now we know how to link Docker containers together the next step is
 learning how to manage data, volumes and mounts inside our containers.
 
-Go to [Managing Data in Containers](containers/dockervolumes.md).
+Go to [Managing Data in Containers](../tutorials/dockervolumes.md).
 
 ## Docker products that complement Engine
 

docs/userguide/networking/default_network/dockerlinks.md

@@ -11,7 +11,7 @@ weight=-2
 
 # Legacy container links
 
-The information in this section explains legacy container links within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker. 
+The information in this section explains legacy container links within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker.
 
 Before the [Docker networks feature](../dockernetworks.md), you could use the
 Docker link feature to allow containers to discover each other and securely
@@ -25,7 +25,7 @@ detail on container linking in default `bridge` network.
 
 ## Connect using network port mapping
 
-In [the Using Docker section](../../containers/usingdocker.md), you created a
+In [Run a simple application](../../../tutorials/usingdocker.md), you created a
 container that ran a Python Flask application:
 
     $ docker run -d -P training/webapp python app.py
@@ -33,7 +33,7 @@ container that ran a Python Flask application:
 > **Note:**
 > Containers have an internal network and an IP address
 > (as we saw when we used the `docker inspect` command to show the container's
-> IP address in the [Using Docker](../../containers/usingdocker.md) section).
+> IP address in [Run a simple application](../../../tutorials/usingdocker.md) section).
 > Docker can have a variety of network configurations. You can see more
 > information on Docker networking [here](../index.md).
 

docs/userguide/networking/dockernetworks.md

@@ -95,7 +95,7 @@ worth looking at the default `bridge` network a bit.
 
 
 ### The default bridge network in detail
-The default `bridge` network is present on all Docker hosts. The `docker network inspect` 
+The default `bridge` network is present on all Docker hosts. The `docker network inspect`
 command returns information about a network:
 
 ```
@@ -519,7 +519,7 @@ functionality in user-defined networks.
 
 - [Work with network commands](work-with-networks.md)
 - [Get started with multi-host networking](get-started-overlay.md)
-- [Managing Data in Containers](../containers/dockervolumes.md)
+- [Managing Data in Containers](../../tutorials/dockervolumes.md)
 - [Docker Machine overview](https://docs.docker.com/machine)
 - [Docker Swarm overview](https://docs.docker.com/swarm)
 - [Investigate the LibNetwork project](https://github.com/docker/libnetwork)