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

Pushing apps with Docker requires 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.

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

  • A registry that supports the Docker Registry HTTP API V2.

  • A registry that presents a valid certificate for HTTPS traffic.

  • That the following port numbers match:

    • The EXPOSE port, set in the image’s Dockerfile, for the container to expose.
    • The PORT environment variable set for the app to listen on. If the app does not specify a PORT, Cloud Foundry uses the default port 8080.

Push a Docker Image From Docker Hub

To deploy a Docker image from a Docker Hub repo, run cf push APP-NAME --docker-image REPO/IMAGE:TAG. Replace the placeholder values in the command as follows:

  • 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 the placeholder values in the command 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, the following command pushes the v2 version of the my-image image from the my-repo repository of the internal-registry.example.com registry on port 5000:

$ 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. Follow the steps below to deploy a Docker image with registry authentication:

  1. Make sure the CF_DOCKER_PASSWORD environment variable is set to the Docker registry user password.
  2. Run the following command: $ CF_DOCKER_PASSWORD=YOUR-PASSWORD cf push APP-NAME --docker-image REPO/IMAGE:TAG --docker-username USER
    Replace the placeholder values in the command 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:
      • For Docker Hub, this is just the repository name
      • For a private registry, this includes the registry address and port, as described in Push a Docker Image from a Private Registry, in the format: MY-PRIVATE-REGISTRY.DOMAIN:PORT/REPO
    • 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

Push a Docker Image From Google Container Registry (GCR)

CF supports pushing apps from images hosted on Google Container Registry (GCR) service. This feature requires that you use json_key based authentication.

Step 1: Authenticate with GCR

To authenticate with GCR using CF, you must create a JSON key file and associate it with your project:

  1. Create a GCP service account. See Creating and Enabling Service Accounts for Instances.

    $ gcloud iam service-accounts create MY-ACCOUNT --display-name "MY DISPLAY NAME"
    

  2. Create a JSON key file and associate it with the service account:

    $ gcloud iam service-accounts keys create key.json --iam-account=MY-ACCOUNT@MY-PROJECT-ID.iam.gserviceaccount.com
    

  3. Set your project ID:

    $ gcloud config set project MY-PROJECT-ID
    

  4. Add the IAM policy binding for your project and service account:

    gcloud projects add-iam-policy-binding MY-PROJECT --member serviceAccount:MY-ACCOUNT@MY-PROJECT-ID.iam.gserviceaccount.com --role roles/storage.objectViewer
    

Step 2: Deploy the GCP Image

Run the following command to deploy your GCR image using the cf CLI: CF_DOCKER_PASSWORD="$(cat key.json)" cf push APP-NAME --docker-image docker://MY-REGISTRY-URL/MY-PROJECT/MY-IMAGE-NAME --docker-username _json_key
Replace the placeholder values in the command as follows:

  • APP-NAME: The name of the app being pushed
  • MY-REGISTRY-URL: The URL of your registry
  • MY-PROJECT: The name of your project
  • MY-IMAGE-NAME: The name of your image

Note: The key.json file must point to the file you created in the previous step.

Note: For information about specifying MY-REGISTRY-URL, see Pushing and Pulling Images on the Google Cloud documentation.

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