Deploy an App with Docker

Page last updated:

This topic describes how to use the Cloud Foundry Command Line Interface (cf CLI) to push an app with a new or updated Docker image. Cloud Foundry then uses the Docker image to create containers for the app.

See the Using Docker in Cloud Foundry topic for an explanation of how Docker works in Cloud Foundry.

Requirements

To push apps with Docker, you need the following:

  • A Cloud Foundry (CF) deployment that has Docker support enabled. To enable Docker support, see the Enable Docker section of Using Docker in Cloud Foundry.

  • A Docker image that meets the following requirements:

    • The Docker image must contain an /etc/passwd file with an entry for the root user. In addition, the home directory and the shell for that root user must be present in the image filesystem.
    • The total size of the Docker image filesystem layers must not exceed the disk quota for the app. The maximum disk allocation for apps is set by the Cloud Controller. The default maximum disk quota is 2048 MB per app.

    Note: If the total size of the Docker image filesystem layers exceeds the disk quota, the app instances do not start.

  • The location of the Docker image on Docker Hub or another Docker registry.

  • A registry that supports the Docker Registry HTTP API V2 and presents a valid certificate for HTTPS traffic.

Note: If you want to log in to your app container using the cf ssh command, a shell such as sh or bash must be available in the container. The SSH server in the container looks for the following executables in absolute locations or the PATH environment variable: /bin/bash, /usr/local/bin/bash, /bin/sh, bash, and sh.

Port Configuration

By default, apps listen for connections on the port specified in the PORT environment variable for the app. Cloud Foundry allocates this value dynamically.

When configuring a Docker image for Cloud Foundry, you can control the exposed port and the corresponding value of PORT by specifying the EXPOSE directive in the image Dockerfile. If you specify the EXPOSE directive, then the corresponding app pushed to Cloud Foundry listens on that exposed port. For example, if you set EXPOSE to 7070, then the app listens for connections on port 7070.

If you do not specify a port in the EXPOSE directive, then the app listens on the value of the PORT environment variable as determined by Cloud Foundry.

If you set the PORT environment variable via an ENV directive in a Dockerfile, Cloud Foundry overrides the value with the system-determined value.

Cloud Foundry supports only one exposed port on the image.

Push a Docker Image From Docker Hub

To deploy a Docker image from a Docker Hub repository, run:

$ cf push APP-NAME --docker-image REPO/IMAGE:TAG

Replace the following values in the command above:

  • APP-NAME: The name of the app being pushed
  • REPO: The name of the repository where the image is stored
  • IMAGE: The name of an image from Docker Hub
  • TAG: (Optional) The tag or version for the image

For example, the following command pushes the my-image image from Docker Hub to a Cloud Foundry app:

$ cf push my-app --docker-image cloudfoundry/my-image

Push a Docker Image from a Private Registry

As an alternative to Docker Hub, you can use any Docker image registry that presents a valid certificate for HTTPS traffic, such as a company-internal Docker registry.

To deploy a Docker image using a specified Docker registry, run:

$ cf push APP-NAME --docker-image MY-PRIVATE-REGISTRY.DOMAIN:PORT/REPO/IMAGE:TAG

Replace values in the command above as follows:

  • APP-NAME: The name of the app being pushed
  • MY-PRIVATE-REGISTRY.DOMAIN: The path to the Docker registry
  • PORT: The port where the registry serves traffic
  • REPO: The name of the repository where the image is stored
  • IMAGE: The name of the image being pushed
  • TAG: (Optional) The tag or version for the image

For example:

$ cf push my-app --docker-image internal-registry.example.com:5000/my-repo/my-image:v2

Push a Docker Image From a Registry with Authentication

Many Docker registries control access to Docker images by authenticating with a username and password. To deploy a Docker image with registry authentication:

  1. With the CF_DOCKER_PASSWORD environment variable set to the Docker registry user password, run cf push with --docker-image and --docker-username:
    $ CF_DOCKER_PASSWORD=YOUR-PASSWORD cf push APP-NAME --docker-image REPO/IMAGE:TAG --docker-username USER
    
    Replace values in the command above as follows:
    • YOUR-PASSWORD: The password to use for authentication with the registry
    • APP-NAME: The name of the app being pushed
    • REPO: The repository where the image is stored:
    • IMAGE: The name of the image being pushed
    • TAG: (Optional) The tag or version for the image
    • USER: The username to use for authentication with the registry

Docker Volume Support

Diego supports Docker volumes. For more information about enabling volume support, see the Using an External File System (Volume Services) topic. For information about the limitations of NFS volumes, see the NFS Bosh Volume Release.

Create a pull request or raise an issue on the source for this page in GitHub