Start Building for Free

Deploy to Cloud Foundry

2 months ago1 min read
Server v4.x
Server v3.x
On This Page

In this how-to guide, you will learn how to configure CircleCI to deploy to Cloud Foundry.


This pages provides a configuration for deployment to Cloud Foundry. CircleCI has developed a CloudFoundry orb that you can use to simplify your configuration workflows. The Cloud Foundry page in the orbs registry contains several different examples of how you can perform tasks with CloudFoundry, including the example below that shows how you can build and run blue green deployment in a single job. In this example, domain will automatically be prefixed with dark and live for two subdomains to be specified. Validation steps would also need to be provided to allow the live deployment to go ahead.

Deploy to Cloud Foundry with the Cloud Foundry orb

Make sure to replace any placeholder versions in the example.

version: 2.1

  cloudfoundry: circleci/cloudfoundry@x.y.z # Use the Cloud Foundry orb in your config

      - cloudfoundry/blue_green:
          appname: <your-app-name>
            - run: echo 'your build steps'
            - run: echo 'you can have more, too'
            - run: echo 'or provide a workspace'
          context: your-context
          domain: your-domain
          manifest: null
          org: your-org
          package: null
          space: your-space
            # Call any orbs or custom commands that validate the health of deployed application before letting Green deploy/reroute proceed.
            # For example,  hitting a /health endpoint with curl and making sure the dark URL returns a 200.

If you would like more detailed information about various CloudFoundry orb elements that you can use in your configuration, refer to the CloudFoundry orb page in the CircleCI Orbs Registry.

Deploy to Cloud Foundry without the orb

Cloud Foundry deployments require the Cloud Foundry CLI. Be sure to match the architecture to your Docker image (the commands below assume you are using a Debian-based image). This example pattern implements "Blue-Green" deployments using Cloud Foundry’s map-route/unmap-route commands, which is an optional feature above and beyond a basic cf push.

1. Install the CLI

      - run:
          name: Setup CF CLI
          command: |
            curl -v -L -o cf-cli_amd64.deb ""
            sudo dpkg -i cf-cli_amd64.deb
            cf -v
            cf api  # alternately target your private Cloud Foundry deployment
            cf auth "$CF_USER" "$CF_PASSWORD"
            cf target -o "$CF_ORG" -s "$CF_SPACE"

2. Dark deployment

      - run:
          name: CF Deploy
          command: |
            # push artifacts on "dark" subdomain, and set environment variables before running `cf start`.
            cf push --no-start <app-name-dark> -f manifest.yml -p application.jar -n dark -d <>
            # Pass CircleCI variables to Cloud Foundry (optional)
            cf set-env <app-name-dark> circle_build_num ${CIRCLE_BUILD_NUM}
            cf set-env <app-name-dark> circle_commit ${CIRCLE_SHA1}
            cf set-env <app-name-dark> circle_workflow_guid ${CIRCLE_WORKFLOW_ID}
            cf set-env <app-name-dark> circle_user ${CIRCLE_PROJECT_USERNAME}
            cf set-env <app-name-dark> circle_repo ${CIRCLE_PROJECT_REPONAME}
            # Start the application
            cf start <app-name-dark>
            # Ensure dark route is exclusive to dark app
            cf unmap-route <app-name> <> -n dark || echo "Dark Route Already exclusive"

3. Live deployment

Until now, the previously pushed "app-name" has not changed. The final step is to route the production URL to our dark application, stop traffic to the previous version, and rename the applications.

      - run:
          name: Re-route live Domain to latest
          command: |
            # Send "real" url to new version
            cf map-route app-name-dark -n www
            # Stop sending traffic to previous version
            cf unmap-route app-name -n www
            # stop previous version
            cf stop app-name
            # delete previous version
            cf delete app-name -f
            # Switch name of "dark" version to claim correct name
            cf rename app-name-dark app-name

4. Manual approval (optional)

For additional control or validation, you can add a manual "hold" step between the dark and live steps as shown in the sample workflow below.

      - test
      - dark-deploy:
            - test
              only: main
      - hold:
          type: approval
            - dark-deploy
              only: main
      - live-deploy:
            - hold # manual approval required via the CircleCI UI to run the live-deploy job
              only: main

Suggest an edit to this page

Make a contribution
Learn how to contribute