Better examples to show Compose file structure, expand/collapse accordion (#3967)

* better examples to show Compose file structure

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* cleaned up leading spaces in Compose file example

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* cleaned up leading spaces, added a test file

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* expand/collapse accordion full implementation, explanation in test.md

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* delete temporary test file from PR

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* fix accordion to work on mobile (cursor style)

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* verified fix for mobile worked, added same to test.md, updated notes and content

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* Clarifed details on test page, fixed references for FontAwesome icons

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
This commit is contained in:
Victoria Bialas 2017-07-28 12:32:53 -07:00 committed by GitHub
parent 52644895c0
commit eb25815fb9
4 changed files with 285 additions and 16 deletions

View File

@ -58,10 +58,37 @@ i.fa.fa-outdent {
padding: 0px 15px 10px 15px;
}
/*
*
* Inline graphics and icons (like the whale menu icon in d4mac, d4win)
*
*/
img.inline {
display: inline;
}
/*
*
* Bootstrap expand/collapse accordions
*
*/
.panel-heading .chevron:after {
content: "\f0d8";
}
.panel-heading.collapsed .chevron:after {
content: "\f0d7";
}
.panel-heading:hover{
background: #fafdfe;
}
/*
* Search *********************************************************************
*

View File

@ -31,10 +31,6 @@ a section in the configuration file such as `build`, `deploy`, `depends_on`,
sub-topics. This maps to the `<key>: <option>: <value>` indent structure of the
Compose file.
The best way to grok the layout and syntax of a Compose file is to
read [Get started with Docker Compose](/compose/gettingstarted/) and look
at files included in [sample applications](https://docs.docker.com/samples/).
A good place to start is the [Getting Started](/get-started/index.md) tutorial
which uses version 3 Compose stack files to implement multi-container apps,
service definitions, and swarm mode. Here are some Compose files used in the
@ -44,8 +40,110 @@ tutorial.
- [Adding a new service and redeploying](/get-started/part5.md#adding-a-new-service-and-redeploying)
Another example of a Compose file is included in the Docker Labs topic, [Deploying an app to a Swarm](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md).
Another good example is the Compose file for the voting app sample used in the
[Docker for Beginners lab](https://github.com/docker/labs/tree/master/beginner/)
topic on [Deploying an app to a
Swarm](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md).
Click to show/hide the example Compose file below.
<div class="panel panel-default">
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
Example Compose file version 3
<i class="chevron fa fa-fw"></i></div>
<div class="collapse block" id="collapseSample1">
<pre><code>
version: "3"
services:
redis:
image: redis:alpine
ports:
- "6379"
networks:
- frontend
deploy:
replicas: 2
update_config:
parallelism: 2
delay: 10s
restart_policy:
condition: on-failure
db:
image: postgres:9.4
volumes:
- db-data:/var/lib/postgresql/data
networks:
- backend
deploy:
placement:
constraints: [node.role == manager]
vote:
image: dockersamples/examplevotingapp_vote:before
ports:
- 5000:80
networks:
- frontend
depends_on:
- redis
deploy:
replicas: 2
update_config:
parallelism: 2
restart_policy:
condition: on-failure
result:
image: dockersamples/examplevotingapp_result:before
ports:
- 5001:80
networks:
- backend
depends_on:
- db
deploy:
replicas: 1
update_config:
parallelism: 2
delay: 10s
restart_policy:
condition: on-failure
worker:
image: dockersamples/examplevotingapp_worker
networks:
- frontend
- backend
deploy:
mode: replicated
replicas: 1
labels: [APP=VOTING]
restart_policy:
condition: on-failure
delay: 10s
max_attempts: 3
window: 120s
placement:
constraints: [node.role == manager]
visualizer:
image: dockersamples/visualizer:stable
ports:
- "8080:8080"
stop_grace_period: 1m30s
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
deploy:
placement:
constraints: [node.role == manager]
networks:
frontend:
backend:
volumes:
db-data:
</code></pre>
</div>
</div>
## Service configuration reference
@ -79,16 +177,28 @@ definition in version 3.
Configuration options that are applied at build time.
`build` can be specified either as a string containing a path to the build
context, or an object with the path specified under [context](#context) and
optionally [dockerfile](#dockerfile) and [args](#args).
context:
```none
version: '2'
services:
webapp:
build: ./dir
```
Or, as an an object with the path specified under [context](#context) and
optionally [Dockerfile](#dockerfile) and [args](#args):
```none
version: '2'
services:
webapp:
build:
context: ./dir
dockerfile: Dockerfile-alternate
args:
buildno: 1
```
If you specify `image` as well as `build`, then Compose names the built image
with the `webapp` and optional `tag` specified in `image`:
@ -783,7 +893,7 @@ list are processed from the top down. For the same variable specified in file
listed below (after), then the value from `b.env` stands. For example, given the
following declaration in `docker_compose.yml`:
```yaml
```none
services:
some-service:
env_file:
@ -1093,7 +1203,10 @@ The general format is shown here.
aliases:
- alias2
In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network.
In the example below, three services are provided (`web`, `worker`, and `db`),
along with two networks (`new` and `legacy`). The `db` service is reachable at
the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on
the `legacy` network.
version: '2'
@ -1387,13 +1500,53 @@ more information.
### volumes
Mount host paths or named volumes, specified as sub-options to a service.
You can mount a host path as part of a definition for a single service, and
there is no need to define it in the top level `volumes` key.
But, if you want to reuse a volume across multiple services, then define a named
volume in the [top-level `volumes` key](#volume-configuration-reference). Use
named volumes with [services, swarms, and stack
files](#volumes-for-services-swarms-and-stack-files).
> **Note**: The top-level
> [volumes](#volume-configuration-reference) option defines
> [volumes](#volume-configuration-reference) key defines
> a named volume and references it from each service's `volumes` list. This replaces `volumes_from` in earlier versions of the Compose file format. (See [Docker Volumes](/engine/userguide/dockervolumes.md) and
[Volume Plugins](/engine/extend/plugins_volume.md) for general information on volumes.)
Mount host paths or named volumes. Named volumes must be defined in the
[top-level `volumes` key](#volume-configuration-reference). Use named volumes with [services, swarms, and stack files](#volumes-for-services-swarms-and-stack-files).
This example shows a named volume (`db-data`) being used by the `postgres` service, and a mounted volume for a single service (under the `redis` service).
```none
version: "3"
services:
web:
nginx:alpine
ports:
- "80:80"
postgres:
image: postgres:9.4
volumes:
- db-data:/var/lib/db
backup:
image: postgres:9.4
volumes:
- db-data:/var/lib/backup/data
redis:
image: redis
ports:
- "6379:6379"
volumes:
- ./data:/data
volumes:
db-data:
```
#### Short syntax
@ -1440,6 +1593,16 @@ expressed in the short form.
```none
version: "3"
services:
web:
image: nginx:alpine
ports:
- "80:80"
networks:
webnet:
volumes:
- type: volume
source: mydata
@ -1475,7 +1638,7 @@ Labs](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md)
configured as a named volume in order to persist the data on the swarm,
_and_ is constrained to run only on `manager` nodes. Here is the relevant snip-it from that file:
```
```none
version: "3"
services:
db:
@ -1511,7 +1674,7 @@ are visible on the host.
Here is an example of configuring a volume as `cached`:
```
```none
version: '3'
services:
php:
@ -1526,7 +1689,6 @@ Full detail on these flags, the problems they solve, and their
`docker run` counterparts is in the Docker for Mac topic [Performance tuning for
volume mounts (shared filesystems)](/docker-for-mac/osxfs-caching.md).
### restart
`no` is the default restart policy, and it will not restart a container under

View File

@ -156,7 +156,7 @@ and destroy isolated testing environments for your test suite. By defining the f
Compose has traditionally been focused on development and testing workflows,
but with each release we're making progress on more production-oriented features. You can use Compose to deploy to a remote Docker Engine. The Docker Engine may be a single instance provisioned with
[Docker Machine](/machine/overview.md) or an entire
[Docker Swarm](/swarm/overview.md) cluster.
[Docker Swarm](/engine/swarm/index.md) cluster.
For details on using production-oriented features, see
[compose in production](production.md) in this documentation.

80
test.md
View File

@ -335,6 +335,86 @@ then it will take up the whole row.</div>
then it will take up the whole row.</div>
</div>
### Expand/Collapse accordions
You can use the Bootstrap and CSS to add expand/collapse accordions. This
implementation makes use of the `.panel-heading` classes in
[`_utilities.scss`](/_scss/_utilities.scss), along with [FontAwesome
icons](http://fontawesome.io/cheatsheet/){: target="_blank" class="_" }
<i class="fa fa-caret-down" aria-hidden="true"></i> (fa-caret-down) and
<i class="fa fa-caret-up" aria-hidden="true"></i> (fa-caret-up).
Adding `block` to the `div` class `collapse` gives you some padding around the
sample content. This works nicely for standard text. If you have a code sample,
the padding renders as white space around the code block grey background. If we
don't like this effect, we can remove `block` for code samples.
The `style="cursor: pointer"` tag enables the expand/collapse functionality to
work on mobile. (You can use the [Xcode iPhone simulator](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/GettingStartedwithiOSSimulator/GettingStartedwithiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH5-SW4){: target="_blank" class="_" } to test on mobile.)
There are a lot of samples out there for Bootstrap accordions. This is the model
we used: [PPxOJX accordion sample with HTML and
CSS](https://codepen.io/anon/pen/PPxOJX){: target="_blank" class="_" }. (Here is
another example, but it uses Javascript, whereas the implementation shown
[here](https://www.bootply.com/89084){: target="_blank" class="_" } is Bootstrap
and CSS only.)
> Make sure `data-target`'s and `id`'s match, and are unique
>
>For each drop-down, the value for `data-target` and
`collapse` `id` must match, and id's must be unique per page. In this example,
we name these `collapseSample1` and `collapseSample2`. Check out the
[Compose file structure example](/compose/compose-file/index.md#compose-file-structure-and-examples)
to see another example.
{: .important-vanilla}
<div class="panel panel-default">
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
Docker hello-world example
<i class="chevron fa fa-fw"></i></div>
<div class="collapse block" id="collapseSample1">
<pre><code>
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b04784fba78d: Pull complete
Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
Share images, automate workflows, and more with a free Docker ID:
https://cloud.docker.com/
For more examples and ideas, visit:
https://docs.docker.com/engine/userguide/
</code></pre>
</div>
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample2" style="cursor: pointer"> Another Sample <i class="chevron fa fa-fw"></i></div>
<div class="collapse block" id="collapseSample2">
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.</p>
</div>
</div>
### Columnar text
You can use the CSS `column-count` to flow your text into multiple columns.