docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Style edits - note 'TBA' at end

This commit is contained in:
paigehargrave 2019-06-12 13:54:05 -04:00 committed by GitHub
parent c227993f29
commit 3da9b9673f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 92 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
app/working-with-app.md
View File

@ -6,7 +6,8 @@ keywords: Docker App, applications, compose, orchestration
## Overview
Docker App is a CLI plug-in that introduces a top-level `docker app` command that brings the _container experience_ to applications. The following table compares Docker containers with Docker applications.
Docker App is a CLI plug-in that introduces a top-level `docker app` command to bring
the _container experience_ to applications. The following table compares Docker containers with Docker applications.
| Object | Config file | Build with | Execute with | Share with |
@ -15,41 +16,43 @@ Docker App is a CLI plug-in that introduces a top-level `docker app` command tha
| App | App Package | docker app bundle | docker app install | docker app push |
With Docker App, entire applications can now be managed as easily as images and containers. For example, Docker App lets you _build_, _validate_ and _deploy_ applications with the `docker app` command. You can even leverage secure supply-chain features such as signed `push` and `pull` operations.
With Docker App, entire applications can now be managed as easily as images and containers. For example,
Docker App lets you _build_, _validate_ and _deploy_ applications with the `docker app` command. You can
even leverage secure supply-chain features such as signed `push` and `pull` operations.
> **NOTE**: `docker app` works with `Engine - Community 19.03` or higher and `Engine - Enterprise 19.03` or higher.
This guide will walk you through two scenarios:
This guide walks you through two scenarios:
1. Initialize and deploy a new Docker App project from scratch
1. Convert an existing Compose app into a Docker App project (added later in the beta process)
1. Initialize and deploy a new Docker App project from scratch.
1. Convert an existing Compose app into a Docker App project (added later in the beta process).
The first scenario will familiarize you with the basic components of a Docker App and get you comfortable with the tools and workflow.
The first scenario describes basic components of a Docker App with tools and workflow.
## Initialize and deploy a new Docker App project from scratch
In this section, we'll walk through the process of creating a new Docker App project. By then end, you'll be familiar with the workflow and most important commands.
We'll complete the following steps:
This section describes the steps for creating a new Docker App project to familiarize you with the workflow and most important commands.
1. Prerequisites
1. Initialize an empty new project
1. Populate the project
1. Validate the app
1. Deploy the app
1. Push the app to Docker Hub
1. Install the app directly from Docker Hub
2. Initialize an empty new project
3. Populate the project
4. Validate the app
5. Deploy the app
6. Push the app to Docker Hub
7. Install the app directly from Docker Hub
### Prerequisites
In order to follow along, you'll need at least one Docker node operating in Swarm mode. You will also need the latest build of the Docker CLI with the App CLI plugin included.
Depending on your Linux distribution and your security context, you may need to prepend commands with `sudo`.
You need at least one Docker node operating in Swarm mode. You also need the latest build of the Docker CLI
with the App CLI plugin included.
Depending on your Linux distribution and your security context, you might need to prepend commands with `sudo`.
### Initialize a new empty project
The `docker app init` command is used to initialize a new Docker application project. If you run it on its own, it initializes a new empty project. If you point it to an existing `docker-compose.yml` file, it initializes a new project based on the Compose file.
The `docker app init` command is used to initialize a new Docker application project. If you run it on
its own, it initializes a new empty project. If you point it to an existing `docker-compose.yml` file,
it initializes a new project based on the Compose file.
Use the following command to initialize a new empty project called "hello-world".
@ -58,20 +61,25 @@ $ docker app init --single-file hello-world
Created "hello-world.dockerapp"
```
The command will produce a single file in your current directory called `hello-world.dockerapp`. The format of the file name is <project-name> appended with `.dockerapp`.
The command produces a single file in your current directory called `hello-world.dockerapp`.
The format of the file name is <project-name> appended with `.dockerapp`.
```
$ ls
hello-world.dockerapp
```
If you run `docker app init` without the `--single-file` flag you will get a new directory containing three YAML files. The name of the directory will be the name of the project with `.dockerapp` appended, and the three YAML files will be:
If you run `docker app init` without the `--single-file` flag, you get a new directory containing three YAML files.
The name of the directory is the name of the project with `.dockerapp` appended, and the three YAML files are:
- `docker-compose.yml`
- `metadata.yml`
- `parameters.yml`
However, the `--single-file` option merges the three YAML files into a single YAML file with three sections. Each of these sections relates to one of the three YAML files mentioned above:`docker-compose.yml`, `metadata.yml`, and `parameters.yml`. Using the `--single-file` option is great for enabling you to share your application via a single configuration file.
However, the `--single-file` option merges the three YAML files into a single YAML file with three sections.
Each of these sections relates to one of the three YAML files mentioned previously: `docker-compose.yml`,
`metadata.yml`, and `parameters.yml`. Using the `--single-file` option enables you to share your application
via a single configuration file.
Inspect the YAML with the following command.
@ -89,21 +97,23 @@ services: {}
# Default application parameters - equivalent to parameters.yml.
```
Your file may be more verbose.
Your file might be more verbose.
Notice that each of the three sections is separated by a set of three dashes ("---"). Let's quickly describe each section.
The first section of the file is where you specify identification metadata such as name, version, description and maintainers. It accepts key-value pairs. This part of the file can be a separate file called `metadata.yml`
The first section of the file specifies identification metadata such as name, version,
description and maintainers. It accepts key-value pairs. This part of the file can be a separate file called `metadata.yml`
The second section of the file describes the application. It can be a separate file called `docker-compose.yml`.
The final section is where default values for application parameters can be expressed. It can be a separate file called `parameters.yml`
The final section specifies default values for application parameters. It can be a separate file called `parameters.yml`
### Populate the project
In this section, we'll edit the project YAML file so that it runs a simple web app.
This section describes editing the project YAML file so that it runs a simple web app.
Use your preferred editor to edit the `hello-world.dockerapp` YAML file and update the application section to the following:
Use your preferred editor to edit the `hello-world.dockerapp` YAML file and update the application section with
the following information:
```
version: "3.6"
@ -127,11 +137,16 @@ The sections of the YAML file are currently order-based. This means it's importa
Save the changes.
The application has been updated to run a single-container application based on the `hashicorp/http-echo` web server image. This image will have it execute a single command that displays some text and exposes itself on a network port.
The application is updated to run a single-container application based on the `hashicorp/http-echo` web server image.
This image has it execute a single command that displays some text and exposes itself on a network port.
Following best practices, the configuration of the application has been decoupled form the application itself using variables. In this case, the text displayed by the app, and the port it will be published on, are controlled by two variables defined in the `Parameters` section of the file.
Following best practices, the configuration of the application is decoupled form the application itself using variables.
In this case, the text displayed by the app and the port on which it will be published are controlled bytwo variables defined in the `Parameters` section of the file.
Docker App provides the `inspect` subcommand to provide a prettified summary of the application configuration. It is a quick way to check how to configure the application before deployment, without having to read the `Compose file`. It's important to note that the application is not running at this point, and that the `inspect` operation inspects the configuration file(s).
Docker App provides the `inspect` subcommand to provide a prettified summary of the application configuration.
It is a quick way to check how to configure the application before deployment, without having to read
the `Compose file`. It's important to note that the application is not running at this point, and that
the `inspect` operation inspects the configuration file(s).
```
$ docker app inspect hello-world.dockerapp
@ -147,19 +162,22 @@ hello.port 8080
hello.text Hello world!
```
`docker app inspect` operations will fail if the `Parameters` section doesn't specify a default value for every parameter expressed in the app section.
`docker app inspect` operations fail if the `Parameters` section doesn't specify a default value for
every parameter expressed in the app section.
The application is ready to be validated and rendered.
### Validate the app
Docker App provides the `validate` subcommand to check syntax and other aspects of the configuration. If the app passes validation, the command returns no arguments.
Docker App provides the `validate` subcommand to check syntax and other aspects of the configuration.
If the app passes validation, the command returns no arguments.
```
$ docker app validate hello-world.dockerapp
Validated "hello-world.dockerapp"
```
`docker app validate` operations will fail if the `Parameters` section doesn't specify a default value for every parameter expressed in the app section.
`docker app validate` operations fail if the `Parameters` section doesn't specify a default value for
every parameter expressed in the app section.
As the `validate` operation has returned no problems, the app is ready to be deployed.
@ -167,15 +185,15 @@ As the `validate` operation has returned no problems, the app is ready to be dep
There are several options for deploying a Docker App project.
1. Deploy as a native Docker App application
1. Deploy as a Compose app application
1. Deploy as a Docker Stack application
- Deploy as a native Docker App application
- Deploy as a Compose app application
- Deploy as a Docker Stack application
We'll look at all three options, starting with deploying as a native Dock App application.
All three options are discussed, starting with deploying as a native Dock App application.
#### Deploy as a native Docker App
The process for deploying as a native Docker app is as follows.
The process for deploying as a native Docker app is as follows:
1. Use `docker app install` to deploy the application
@ -188,7 +206,10 @@ Creating service my-app_hello
Application "my-app" installed on context "default"
```
By default `docker app` uses the [current context](../engine/context/working-with-contexts) to run the installation container and as a target context to deploy the application. This second context can be overridden using the flag `--target-context` or the environment variable `DOCKER_TARGET_CONTEXT`. This flag is also available for the commands `status`, `upgrade` and `uninstall`.
By default, `docker app` uses the [current context](../engine/context/working-with-contexts) to run the
installation container and as a target context to deploy the application. This second context can be overridden
using the flag `--target-context` or the environment variable `DOCKER_TARGET_CONTEXT`. This flag is also
available for the commands `status`, `upgrade` and `uninstall`.
```
$ docker app install hello-world.dockerapp --name my-app --target-context=my-big-production-cluster
@ -197,7 +218,8 @@ Creating service my-app_hello
Application "my-app" installed on context "my-big-production-cluster"
```
> **NOTE**: Two applications deployed on the same target context cannot share the same name, but this is valid if they are deployed on different target contexts.
> **NOTE**: Two applications deployed on the same target context cannot share the same name, but this is
valid if they are deployed on different target contexts.
You can check the status of the app with the `docker app status <app-name>` command.
@ -238,9 +260,11 @@ NAME SERVICES ORCHESTRATOR
my-app 1 Swarm
```
Now that the app is running, you can point a web browser at the DNS name or public IP of the Docker node on port 8080 and see the app in all its glory. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host.
Now that the app is running, you can point a web browser at the DNS name or public IP of the Docker node on
port 8080 and see the app. You must ensure traffic to port 8080 is allowed on
the connection form your browser to your Docker host.
Let's now change the port of the application, using `docker app upgrade <app-name>` command.
Now change the port of the application using `docker app upgrade <app-name>` command.
```
$ docker app upgrade my-app --hello.port=8181
Upgrading service my-app_hello
@ -251,14 +275,14 @@ You can uninstall the app with `docker app uninstall my-app`.
#### Deploy as a Docker Compose app
The process for deploying a as a Compose app comprises two major steps:
The process for deploying as a Compose app comprises two major steps:
1. Render the Docker app project as a `docker-compose.yml` file.
1. Deploy the app using `docker-compose up`.
2. Deploy the app using `docker-compose up`.
You will need a recent version of Docker Compose to complete these steps.
You need a recent version of Docker Compose to complete these steps.
Rendering is the process of reading the entire application configuration and outputting it as a single `docker-compose.yml` file. This will create a Compose file with hard-coded values wherever a parameter was specified as a variable.
Rendering is the process of reading the entire application configuration and outputting it as a single `docker-compose.yml` file. This creates a Compose file with hard-coded values wherever a parameter was specified as a variable.
Use the following command to render the app to a Compose file called `docker-compose.yml` in the current directory.
@ -284,7 +308,8 @@ services:
protocol: tcp
```
Notice that the file contains hard-coded values that were expanded based on the contents of the Parameters section of the project's YAML file. For example, ${hello.text} has been expanded to "Hello world!".
Notice that the file contains hard-coded values that were expanded based on the contents of the Parameters
section of the project's YAML file. For example, ${hello.text} has been expanded to "Hello world!".
> **NOTE**: Almost all the `docker app` commands propose the `--set key=value` flag to override a default parameter.
@ -314,7 +339,8 @@ WARNING: The Docker Engine you're using is running in swarm mode.
<Snip>
```
The application is now running as a Docker compose app and should be reachable on port `8080` on your Docker host. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host.
The application is now running as a Docker compose app and should be reachable on port `8080` on your Docker host.
You must ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host.
You can use `docker-compose down` to stop and remove the application.
@ -323,9 +349,10 @@ You can use `docker-compose down` to stop and remove the application.
Deploying the app as a Docker stack is a two-step process very similar to deploying it as a Docker compose app.
1. Render the Docker app project as a `docker-compose.yml` file.
1. Deploy the app using `docker stack deploy`.
2. Deploy the app using `docker stack deploy`.
We'll assume that you've followed the steps to render the Docker app project as a compose file (shown in the previous section) and that you're ready to deploy it as a Docker Stack. Your Docker host will need to be in Swarm mode.
Compete the steps in the previous section to render the Docker app project as a compose file and make sure
you're ready to deploy it as a Docker Stack. Your Docker host must be in Swarm mode.
```
$ docker stack deploy hello-world-app -c docker-compose.yml
@ -335,17 +362,23 @@ Creating service hello-world-app_hello
The app is now deployed as a Docker stack and can be reached on port `8080` on your Docker host.
Use the `docker stack rm hello-world-app` command to stop and remove the stack. You will need to ensure traffic to port 8080 is allowed on the connection form your browser to your Docker host.
Use the `docker stack rm hello-world-app` command to stop and remove the stack. You must ensure traffic to
port 8080 is allowed on the connection form your browser to your Docker host.
### Push the app to Docker Hub
As mentioned in the intro, `docker app` lets you manage entire applications the same way that we currently manage container images. For example, you can push and pull entire applications from registries like Docker Hub with `docker app push` and `docker app pull`. Other `docker app` commands, such as `install`, `upgrade`, `inspect` and `render` can be performed directly on applications while they are stored in a registry.
As mentioned in the introduction, `docker app` lets you manage entire applications the same way that you
currently manage container images. For example, you can push and pull entire applications from registries like
Docker Hub with `docker app push` and `docker app pull`. Other `docker app` commands, such
as `install`, `upgrade`, `inspect` and `render` can be performed directly on applications while they are
stored in a registry.
Let's see some examples.
Examples are described in the following sections.
Push the application to Docker Hub. To complete this step, you'll need a valid Docker ID and you'll need to be logged in to the registry you are pushing the app to.
Push the application to Docker Hub. To complete this step, you need a valid Docker ID and you must be
logged in to the registry to which you are pushing the app.
Be sure to replace the registry ID in the example below with your own.
Be sure to replace the registry ID in the following example with your own.
```
$ docker app push my-app --tag nigelpoulton/app-test:0.1.0
@ -360,7 +393,8 @@ The app is now stored in the container registry.
### Install the app directly from Docker Hub
Now that the app is pushed to the registry, try an `inspect` and `install` command against it. The location of your app will be different to the one shown in the examples.
Now that the app is pushed to the registry, try an `inspect` and `install` command against it.
The location of your app is different from the one provided in the examples.
```
$ docker app inspect nigelpoulton/app-test:0.1.0
@ -389,7 +423,8 @@ Application "hello-world" installed on context "default"
Test that the app is working.
The app used in these examples is a simple web server that displays the text "Hello world!" on port 8181, your app may be different.
The app used in these examples is a simple web server that displays the text "Hello world!" on port 8181,
your app might be different.
```
$ curl http://localhost:8181