Make your Docker Compose applications reusable, and share them on Docker Hub
Перейти к файлу
Mathieu Champlon a48f773ab0 Add deprecation notice
Signed-off-by: Mathieu Champlon <mathieu.champlon@docker.com>
2021-06-11 16:06:23 +02:00
.github Picture of animal in PR should really be optional 2019-10-30 12:09:07 +01:00
cmd Rename relocated.bundle to AppImage 2019-12-06 10:07:12 +01:00
docs Bump golang to 1.13.10 2020-04-21 13:10:47 +02:00
e2e Fix linter timeout: add some concurrency 2020-04-21 18:12:07 +02:00
examples Fix folder name in example voting app README 2020-04-19 14:44:29 +02:00
hack Add a vendor check 2018-06-11 11:31:03 +02:00
internal Fix linter timeout: add some concurrency 2020-04-21 18:12:07 +02:00
loader Fix linter timeout: add some concurrency 2020-04-21 18:12:07 +02:00
render Vendor Docker CLI to 6318939f30e01585b34eb6a68a54b890a8d54eb0 & gojsonschema to v1.2.0 2019-11-08 13:13:07 +01:00
specification Vendor Docker CLI to 6318939f30e01585b34eb6a68a54b890a8d54eb0 & gojsonschema to v1.2.0 2019-11-08 13:13:07 +01:00
types Print image inspect metadata fields in PascalCase 2019-11-20 11:53:05 +00:00
vendor Bump docker/cli to master revision abafad3df202a691bc07332ea166af548a6cd9a0 2020-04-21 14:14:01 +02:00
.dockerignore Simplify and enhance docker.Makefile 2018-06-11 13:48:00 +02:00
.gitattributes Various cleanings, including missing EOL, typos, comments, ... 2019-01-31 16:46:37 +01:00
.gitignore Forbid variable substitution on `image` field 2019-02-05 11:28:06 +01:00
.golangci.yml Fix linter timeout: add some concurrency 2020-04-21 18:12:07 +02:00
BUILDING.md Add note to enable BuildKit to build in docker 2019-11-07 11:11:06 +00:00
CONTRIBUTING.md Prepare docker/app to be open-source 🎉 2018-06-12 15:29:38 +02:00
DockerAppCLIcommands.png Update README to reflect the UX changes in Docker App 2019-11-13 13:51:55 +01:00
Dockerfile Bump gotestsum to v0.4.2 2020-04-21 16:28:31 +02:00
Dockerfile.invocation-image Bump alpine to 3.11.5 2020-04-21 13:29:26 +02:00
Dockerfile.lint Bump golangci linter to 1.23.0 2020-04-21 16:28:30 +02:00
Gopkg.lock Bump docker/cli to master revision abafad3df202a691bc07332ea166af548a6cd9a0 2020-04-21 14:14:01 +02:00
Gopkg.toml Bump docker/cli to master revision abafad3df202a691bc07332ea166af548a6cd9a0 2020-04-21 14:14:01 +02:00
Jenkinsfile Push cnab-app-base image as a multi-arch image with linux-amd64 and linux-arm64 platforms. 2019-12-09 11:10:24 +01:00
Jenkinsfile.baguette Don't clean source dir on windows step 2020-04-23 19:13:59 +02:00
LICENSE Prepare docker/app to be open-source 🎉 2018-06-12 15:29:38 +02:00
MAINTAINERS Removing myself from maintainers 2019-04-17 17:42:00 +02:00
Makefile Fix linter timeout: add some concurrency 2020-04-21 18:12:07 +02:00
README.md Add deprecation notice 2021-06-11 16:06:23 +02:00
doc.go Add package doc for the root package… 2018-09-06 16:39:39 +02:00
docker.Makefile Fix release script: docker manifest command needs the cli experimental env var 2020-04-22 10:49:11 +02:00
poule.yml Prepare docker/app to be open-source 🎉 2018-06-12 15:29:38 +02:00
vars.mk Bump alpine to 3.11.5 2020-04-21 13:29:26 +02:00

README.md

Docker App

Docker App is a Cloud Native application packaging framework with which developers and devops can build, share, and run a set of microservices as a single entity. Docker Apps are based on the Compose format, which permits docker-compose users to easily share their Compose-based multiservice applications via container registries. By leveraging containers, Docker App makes it possible to easily change parts of the application and to share the application through container registries.

Table of Contents

What are the benefits offered by Docker App?

  • Simple management of Docker Apps across different teams and between different environments (Development/QA/Staging/Production)
  • Easy sharing of multi-service applications to container registries (e.g., Docker Hub or Docker Trusted Registry)
  • Having a clear separation of parameters to be modified at runtime
  • Support for multiple orchestrators (Swarm or Kubernetes)
  • Provides the very same UX flow as the one for Docker images
  • Implements the CNAB industry standard
  • Offers full support for Docker Contexts

How does Docker App work?

The Docker App workflow is quite similar to the Docker image workflow. From an App definition, you can build an App image, share it on Docker Hub, and run your App on an orchestrator.

Image showing Docker CLI command flow

Using Docker App

Four primary steps comprise the Docker App process:

  1. Writing an App Definition
  2. Building an App Image
  3. Sharing the App on the Hub (optional)
  4. Running the App

Writing an App definition

The first step in using Docker App is to write the App definition. This definition can be created (1) from an existing Compose file using the docker app init command (2) via a template from the Application Designer, or (3) from scratch.

The App definition is a .dockerapp folder that contains three distinct pieces: metadata, a service list, and the parameters.

File Description
metadata.yml metadata including the App name and version
docker-compose.yml Service list defined in a Compose file
parameters.yml Parameters that can be changed when running the App

*Note: To store additional files in Docker Apps, such as prod.yml, test.yml or other config files, you need only to add these files to the .dockerapp directory. All files will be packaged into the App image through the use of the docker app build command.

Building an App image

Once the App definition is written, the next step is to build the App image from the App definition using the docker app build command. With this command you can tag your App image, set build-time variables, or make the build quiet.

Note that service images inside of an App image are immutable, meaning that the App version ties to a fixed list of service images (i.e., updating the images inside of a Docker App requires rebuilding the App image). This makes deploying applications more deterministic.

Sharing the App on the Hub

You can push any App image already built or pulled to Docker Hub (or any OCI compliant registry) using the docker app push command. You can also pull App images from any OCI compliant registry using the docker app pull command.

When pushing an App image, all the service images used by the application are pushed at the same time inside a single entity. The version of each service image is resolved at build time from its tag.

Running the App

The final Docker App step is to actually run your App using the docker app run command. You can either pick up an App image from Docker Hub or one that you built locally and deploy it to Swarm or Kubernetes.

Example

Using the hello-world application example, we are going to build, share, and run a Docker App that launches an HTTP server that prints the text variable value when hit on the configured port.

Note: Before starting, confirm that the Docker App CLI plugin is installed on your machine

App definition

First, create an App definition from an existing Compose file.

Create a docker-compose.yml file that has the following content:

version: '3.6'
services:
  hello:
    image: hashicorp/http-echo
    command: ["-text", "hello world"]
    ports:
      - 5678:5678

Next, create an App definition using the docker app init command:

$ docker app init --compose-file docker-compose.yml hello
Created "hello.dockerapp"
$ tree
.
├── docker-compose.yml
├── hello.dockerapp
    ├── docker-compose.yml
    ├── metadata.yml
    └── parameters.yml

A new folder named hello.dockerapp now exists, which contains three YAML documents:

  • metadata
  • a Compose file
  • parameters for your application to be used at runtime

The metadata.yml file should display as follows:

version: 0.1.0
name: hello
description: A simple text server
maintainers:
- name: yourusername
  email:

The Compose file is the one that was passed in parameters. Thus, if you open parameters.yml you will notice that it is empty, as the Compose file isnt using any variable.

Using parameters

Edit the docker-compose.yml file in the hello.dockerapp directory to add some variables:

version: '3.6'
services:
  hello:
    image: hashicorp/http-echo
    command: ["-text", "${text}"]
    ports:
      - ${port}:5678

Next, define the default values for the App in the parameters.yml file:

port: 5678
text: hello development

Building an App image

Next, build an App image:

$ docker app build . -f hello.dockerapp -t myrepo/hello:0.1.0
[+] Building 0.7s (6/6) FINISHED
(...) (Build output)
sha256:4a492748ae55170daadd1ddfff4db30e0ef3d38bf0f57a913512caa323e140de

At this point, an App image with the myrepo/hello:1.0.1 tag has been built from the hello.dockerapp App definition. This immutable App image includes all the service images at fixed versions that you can run or share.

Sharing and running the App

To share your App image, push it to a container registry.

$ docker app push myrepo/hello:0.1.0

Now run your App:

$ docker app run myrepo/hello:0.1.0 

You can specify the Docker endpoint where an application is installed using a context. By default, your App will run on the currently active context. You can select another context with the docker context use command, and the docker app run command will thereafter run your app on this particular context.

Whenever you define such a context, the installer image will run in the default context (i.e., on local host). You can then use the --installer-context to target another context to run the installer image.

$ docker context create remote --description "remote cluster" --docker host=tcp://<remote-ip>:<remote-port>
Successfully created context "remote"

$ docker context ls
NAME                DESCRIPTION                               DOCKER ENDPOINT               KUBERNETES ENDPOINT                ORCHESTRATOR
default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock   https://localhost:6443 (default)   swarm
remote              remote cluster                            tcp://<remote-ip>:<remote-port>

$ docker context use remote
$ docker app run myrepo/hello:0.1.0

CNAB

Docker Apps are Dockers implementation of the industry standard Cloud Native Application Bundle (CNAB). CNAB is an industry specification put in place to facilitate the bundling, sharing, installing and managing of cloud-native apps that are not only made up of containers but also from such things as hosted databases, functions, etc. Docker App is designed to abstract as many CNAB specifics as possible, to provide users with a tool that is easy to use while alleviating the need to bother with the CNAB specification.

Installation

Docker App is a command line plugin (not be confused with docker engine plugins) that extends the docker command with app sub-commands. It requires Docker CLI 19.03.0 or later, with experimental features enabled. Either set environment variable DOCKER_CLI_EXPERIMENTAL=enabled or update your docker CLI configuration.

Note: The docker plugin install command cannot be used to install Docker-app.

Linux or macOS

Download your OS tarball:

export OSTYPE="$(uname | tr A-Z a-z)"
curl -fsSL --output "/tmp/docker-app-${OSTYPE}.tar.gz" "https://github.com/docker/app/releases/download/v0.8.0/docker-app-${OSTYPE}.tar.gz"
tar xf "/tmp/docker-app-${OSTYPE}.tar.gz" -C /tmp/

Install as a Docker CLI plugin:

mkdir -p ~/.docker/cli-plugins && cp "/tmp/docker-app-plugin-${OSTYPE}" ~/.docker/cli-plugins/docker-app

Windows

Download the Windows tarball:

Invoke-WebRequest -Uri https://github.com/docker/app/releases/download/v0.8.0/docker-app-windows.tar.gz -OutFile docker-app.tar.gz -UseBasicParsing
tar xf "docker-app.tar.gz"

Install as a Docker CLI plugin:

New-Item -ItemType Directory -Path ~/.docker/cli-plugins -ErrorAction SilentlyContinue
cp docker-app-plugin-windows.exe ~/.docker/cli-plugins/docker-app.exe

Next steps

If you're interested in contributing to the project, jump to BUILDING.md and CONTRIBUTING.md.

Further examples are available in the examples directory.