app

README

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?
• How does Docker App work?
• Using Docker App
  • Writing an App definition
  • Building an App image
  • Sharing the App on the Hub
  • Running the App
• Example
  • App definition
  • Using parameters
  • Building an App image
  • Sharing and running the App
• CNAB
• Installation
  • Linux or macOS
  • Windows
• Next steps

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.

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 isn’t 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 Docker’s 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.

Documentation

Overview

Package app provides experimental utilities to make Compose files more reusable and sharable.

The `cmd/docker-app` package generates the `docker-app` binary, see https://github.com/docker/app for more information about it.

It can also be used as a library to be integrated in your tools. Usage examples are provided inline with their full documentation.