A Cloud Foundry CLI plugin for downloading running Applications
Occasionally, a developer might need to retrieve source code from his or her running PaaS application that is running on Bluemix or on another Cloud Foundry-based PaaS instance. This is often done while debugging. It allows developers to see what their code looks like after being pushed up, and better understand how build packs are affecting their deployment. On a Cloud Foundry-based PaaS, it’s possible to download a single file at a time through the CF command line interface (cf files) but it’s a tedious and impractical process if many files need to be downloaded.
Therefore, we’ve developed a Cloud Foundry command line plugin to do just that. It builds on the
cf files command, which returns a given file or directory provided a path. We call
cf files behind the scenes, starting with the root directory and recursively working through every subfolder. The response is parsed and written to either a file or directory on the local system.
To install this plugin, you must have the CF CLI version 6.10.0 or higher, and execute the following commands from your terminal:
$ cf add-plugin-repo CF-Community http://plugins.cloudfoundry.org/
$ cf install-plugin cf-download -r CF-Community
So now you can simply execute a command such as
cf download [App Name] and download all the contents of the app to your local file system. (If you ever need to remove this plugin, simple issue the command “cf uninstall-plugin cf-download”.)
Here is the command line syntax for the cf download plugin:
$ cf help download
download - Download contents of a running app's file directory
cf download APP_NAME [PATH] [--overwrite] [--verbose] [--omit ommited_paths] [-i instance_num]
--omit "path/to/file" Omit directories or files delimited by semicolons
--overwrite Overwrite existing files
--verbose Verbose output
To speed up the process, Goroutines are used to parallelize the process by downloading many files at a time. Depending on the size of your application, the entire download might take a few minutes or more. Performance can be improved by omitting files or folders. Files and directories can be omitted by placing their paths in a .cfignore file or by using the omit flag. The .cfignore file works similarly to a .gitignore file, and follows the same syntax for specifying ignored paths. Also like .gitignore, the .cfignore file must be in the directory where the command (in this case cf download) is executed. The omit flag takes paths to files or directories as arguments. Paths always start from the project root. If you want to see what files are in the root you can use the
cf files [app_name] command to get a visual representation of the root of your project. If you wanted to omit multiple files you would use a semicolon separated string in quotes, like this:
- Node example:
cf download MyNodeApp --omit "app/node_modules; app/bin; logs"(By omitting app/node_modules you will greatly decrease download times. You can run npm install locally on your package.json after completing a download.)
- Java example:
cf download MyJavaApp --omit "app/.java; app/.liberty"(because app/.java and app/.liberty directories are very large and contain many permission issues that prevent proper download, it is best to omit them.)
Many projects hosted on Cloud Foundry use package managers to download dependencies while the app is staging. These are often installed into a single directory, and are usually the largest files in a project. Because of this we recommend omitting these directories from your download. In doing so you avoid download errors caused by file permissions, and the download will complete much faster. Some packages have permissions set that do not allow them to be downloaded using cf files. If you still want to have a local copy of your dependencies, then you can run the package manager install locally. A common example of this is the node.js node_modules folder. You can omit this directory using the –omit flag (–omit app/node_modules). Once the download completes you can go ahead and run npm install to get all your dependencies back
Just like cf files, our plugin allows you to specify a path after the app name for targeting a specific directory in the project. So if you had an “images” directory that you wanted to download at app/public/images you would use
cf download [app_name] app/public/images to download that directory. This provides a significant performance boost, because you will only download a small part of the project, instead of the entire thing.
Check out the the plugin here for installation and usage information. Your feedback is appreciated.