RUN@cloud » CloudBees SDK

CloudBees SDK

Last modified by Fabian Donze on 2014/04/10 17:56

The SDK provides command line tools for your workstation to make use of the CloudBees Platform. There are a lot of features in it, but don't worry, all the commands have built in help - just add --help at any point to the end of a command you are trying to use, to get usage details.

Installing the CloudBees SDK

Note on running applications in European region

Note, if you are dealing with applications in the European cloudbees data centre, you can use the flag "-ep eu" flag to tell it to run the command in europe for any of the commands below. If you are often performing actions against the EU region, we recommend you set the api endpoint in the "bees.config" file (~/.bees/bees.config) to be: bees.api.url=https\://api-eu.cloudbees.com/api - to ensure you are always talking to the EU region.

Prerequisites

Java 6 or greater must be installed and the java command must be available on the PATH (verify by running: java -version)

Download and configure the CloudBees SDK

Download the CloudBees SDK and unzip it into a directory on your machine (we'll refer to as BEES_HOME from now on)

To run the CloudBees command line tools, you need to set the BEES_HOME environment variable, and add BEES_HOME to your PATH environment variable.

The first time you run the bees command, you will be prompted to enter your CloudBees email address and password, your API keys will then be cached in your USER_HOME/.bees/bees.config file so that you won't need to enter them for any of the commands. 

Installation for OSX and Linux

Open a command-line console (launch the Terminal application on OSX) and then download SDK zip file and install unzip it into a directory.

curl -L cloudbees-downloads.s3.amazonaws.com/sdk/cloudbees-sdk-1.5.2-bin.zip > bees_sdk.zip
unzip bees_sdk.zip
rm bees_sdk.zip
cd cloudbees-sdk-1.5.2

Add the bees variables to your OS-X/linux command line environment by adding the following lines to your /.bash_profile or /.profile file (you may need to create this file)

export BEES_HOME=~/cloudbees-sdk-1.5.2
export PATH=$PATH:$BEES_HOME

Refresh your terminal's bash session by executing

# source /.bash_profile (or /.profile as the case may be)

Alternate Installation for OSX

If you have the homebrew package manager, then simply run

brew install cloudbees-sdk

Installation for Windows

On Windows, you can open a predefined Bees Console window by double clicking on the BEES_HOME\Bees Console icon. Please avoid a path with spaces in it in your installation directory ! (eg don't use Program Files if you can avoid it). 

Running behind a proxy

If you are running the SDK commands on a machine that is behind a proxy, you may receive "Connection timed out" errors. The SDK supports a full set of proxy parameters:

  • --proxyHost <arg>       API server proxy host
  • --proxyPassword <arg>   API server proxy password
  • --proxyPort <arg>       API server proxy port
  • --proxyUser <arg>       API server proxy user name

To save your proxy configuration, it is best to initialize the SDK with the bees init command with your --proxy parameters.

> bees init   --proxyHost YOUR_PROXY_HOST   --proxyPort YOUR_PROXY_PORT

You can also put those in your USER_HOME/.bees/bees.config file if you already have a bees.config file:

  • bees.api.proxy.host=localhost
  • bees.api.proxy.port=8008
  • bees.api.proxy.user=user1
  • bees.api.proxy.password=pwd1

The maven plugin also supports similar parameters:

  • -Dbees.proxyHost, -Dbees.proxyPort, etc...

Initializing the SDK with API key and secret instead of credentials

If you are signing in CloudBees without credentials using alternative signing methods (GitHub or others), you can initialize the SDK with the bees init command with your API key and secret directly (you can find your API security keys at https://grandcentral.cloudbees.com/user/keys).

bees init --key YOUR_API_KEY --secret YOUR_API_SECRET  --account YOUR_ACCONT_NAME  --endPoint us|eu

Verify your installation

Verify this is running properly by executing the "bees help" command

# bees help
usage: bees <subcommand> [options] [args]

Un-install or complete re-install

If you need to delete or perform a complete re-install of the SDK, there are three (3) set of files to delete:

  1. delete the files in your BEES_HOME directory
    2. delete the USER_HOME/.bees directory
    3. delete the CloudBees SDK files in the maven repository (.m2/repository/com/cloudbees/sdk)

NOTE: if you encounter the following error, please perform a complete re-install of the SDK as outlined above

java.lang.ClassNotFoundException: com.cloudbees.sdk.Bees

Using SDK Commands from DEV@cloud

If you are interested in using the SDK from your DEV@cloud Jenkins builds, it is is pre-installed on DEV@cloud Jenkins slaves.  The SDK is not automatically added to the path on your Jenkins builds, so please see this page for more information about how to use the SDK commands in your builds.

Application Commands

The CloudBees SDK includes a set of commands for managing the  RUN@Cloud Application Service and can be used to perform most operations  that you can do via the web console.  Having these  commands available  in the SDK makes it easier to integrate CloudBees  operations into your  local development workflow and any build automation  for your web  application projects.

All of the application commands can be invoked using the following syntax.

# bees app:<subcommand> [options] [args]

 

app:deploy

Deploy a new version of an application using a WAR archive file

usage: bees app:deploy [options] ARCHIVE_FILE [platform_parameters]
-a,--appid <appId>          application ID (of the form accountName/applicationName)
-t,--type <container_type>  Deployment container type (tomcat | jboss)  Default: tomcat (you can change this later via app:update)
-d,--delta <arg>         true to enable, false to disable delta upload  (default: true)
-e,--environment <env>      environment configurations to deploy
-m,--message <message>      message describing the deployment
-P <arg>                    Application config parameter name=value
-R <arg>                   Runtime config parameter name=value

[platform_parameters] are defined as name=value pairs - place these as the arguments to a deploy or update command. 

Built in platform parameters:

Parameter Description 
jvmPermSize jvmPermSize in MB (see  JVM PermGen Space
securityMode set to "private" to enable basic authentication access to the application, set to "public" to disable basic authentication
stickySession true or false (see Session Affinity)
proxyBuffering false if you wish to use comet/long running connections, true if you want to use NGinx buffering
httpVersion 1.0 or 1.1 (use 1.1 for Web Sockets)
jvmTimeZone set the timezone for the JVM (eg GMT)
jvmFileEncoding set the file encoding (eg UTF-8)
containerSize set the container size (limits memory and CPU) [values: tiny (128MB), small (256MB), medium (512MB), large (1024MB), xlarge (2048MB), free]. The default value is free.
waitForApplicationStart set whether platform should wait for the app to respond to web requests. The default is true.

-P <key=value> are application config parameters.
You can also run bees config:set  to set these application config parameters without deploying an application.  Application configuration parameters will be available to the application as system properties in Tomcat and JBoss containers and JVM apps.

-R <key=value> are application runtime parameters.  Application runtime parameters are used to customize the stack that will run your application.  The supported values will vary with each application stack, so check the documentation for the stack to see which values are supported.

Note: The parameters you set at deployment time will be remembered for the application even if the next time you deploy without them. You can use them safely for secrets etc, and name them as you need (they are provided as system properties to the JVM).

When deploying WAR files, you can optionally use the cloudbees web configuration file 

app:create

Create a new application definition. Note that the application cannot be started until a snapshot is deployed.

usage: bees app:create [options] APPLICATION_ID [platform_parameters]
-a,--appid <appId>          application ID (of the form accountName/applicationName)
-t,--type <container_type>  Deployment container type (tomcat | jboss)  Default: tomcat (you can change this later via app:update)
-P <arg>                    Application config parameter name=value
-R <arg>                   Runtime config parameter name=value

See app:deploy for a list of platform_parameters and a description of the -R and -P options

app:delete

Delete an application

usage: bees app:delete [options] APPLICATION_ID
-a,--appid <appId>   application ID
-f,--force           forced delete without prompting, also known as "Chuck Norris" mode.

app:info

Returns the basic information about an application (such as its URLs and active/sleeping state). If you wish to change a parameter here, you can use app:update. 

usage: bees app:info [options] APPLICATION_ID
-a,--appid <appId>   application ID

app:list

Returns the list of applications available to your account

usage: bees app:list [options]
-a,--account <arg>   Account Name

app:restart

Restarts all deployed instances of an application

usage: bees app:restart [options] APPLICATION_ID
-a,--appid <appId>   application ID
-f,--force           forced restart without prompting

app:stop

Stops all deployed instances of an application and displays a page saying the app is stopped.  This leaves the app in a state where will not reactivate until the app is restarted (via a restart, update, or deploy command)

usage: bees app:stop [options] APPLICATION_ID
-f,--force          force stop without prompting

app:hibernate

Hibernate (temporary stop) all deployed instances of an application.  This leaves the app in a state where it will be automatically reactivated when the app is accessed. Hibernate is the state that free application are automatically set after a certain period of time or inactivity.

usage: bees app:hibernate [options] APPLICATION_ID
-f,--force          force hibernation without prompting

app:tail (tail a log in real time)

Establishes a persistent connection to an application log so that you   can see new messages as they are written to the logs. This is  provides  a "cloud-friendly" replacement for the ubiquitous "tail"  command many  developers use to monitor/debug application log files.

usage: bees app:tail [options] APPLICATION_ID
-a,--appid <appId>   application ID
 -l,--logname <arg>   The log name: server or access (Default:  'server')

app:update

Update an application parameters and restart the application if the application is currently running. You can update most parameters that you can see by running bees app:info
(for example - you can change the container type via bees app:update containerType=play2 - for example)

usage: bees app:update [options] APPLICATION_ID [parameterX=valueY]
-a,--appid <arg>     CloudBees application ID
-f,--force             force update without prompting
-R <arg>               Runtime config parameter name=value
-t,--type <arg>        Application container type
-ss,--snapshot <arg>       Application active snapshot

app:scale

Scale the number of instances of an application up or down (this is scaling out): 

bees app:scale [options] APPLICATION ID
-a,--appid <arg>    CloudBees application ID
-down <x>         scale down by <x>
-up <x>           scale up by <x>


app:proxy:update

Update the proxy/router configuration without restarting the application

usage: bees app:proxy:update [parameter=value]
-a,--appid <arg>       CloudBees Application ID
-al,--alias <arg>        Application domain name aliases (comma delimited list)

Note that if the aliases specified are in use by another application (on the same account), the aliases will be swapped to the application specified

Proxy parameters

Parameter Description 
stickySession true or false (default) (see Session Affinity)
proxyBuffering false if you wish to use comet/long running connections, true if you want to use NGinx buffering
 httpVersion 1.1 or 1.0 - use 1.1 if you want to use Websockets and the application server supports it.

app:resource:list

To list resources in your account (all apps, databases, session stores, SSL details etc) 

bees app:resource:list [options]
-a,--account <arg>   Account Name
-t,--type <arg>      resource type

app:bind - binding databases and services to your application

You can bind your cloudbees database and other resources (eg session store) into your application and have them made available automatically in a container specific way - read more.  Binding also makes variables available to system properties and environment variables (so you don't have to hard code them into your application).

Database commands

The SDK includes a set of commands for managing the  MySQL Database Service.

bees db:<subcommand> [options] [args]

db:create

Create a new MySQL database

usage: bees db:create [options] DATABASE_NAME
-p,--password <password>   Database password
-u,--username <username>   Database username (must be unique)

db:delete

Delete a MySQL database

usage: bees db:delete [options] DATABASE_NAME
-f,--force   forced delete without prompting

db:info

Returns information about connecting to a database

usage: bees db:info [options] DATABASE_NAME
-p,--password   print the database password info

db:list

Returns a list of all the databases associated with your account

usage: bees db:list [options]
-a,--account <arg>   Account Name

db:set

Change your database password

usage: bees db:set [options] DATABASE_NAME
-p,--password <password>  The database password

Snapshot commands

Legacy mySQL databases support snapshots but not backups.

db:snapshot:list

List database snapshots

usage: bees db:snapshot:list [options] DATABASE_NAME

db:snapshot:create

Create a database snapshot

usage: bees db:snapshot:create [options] DATABASE_NAME
-t,--title <arg>    the database snapshot title

db:snapshot:delete
Delete a database snapshot

usage: bees db:snapshot:delete [options] DATABASE_NAME SNAPSHOT_ID
-f,--force    force delete without prompting

db:snapshot:deploy

Deploy a database snapshot

usage: bees db:snapshot:deploy [options] DATABASE_NAME SNAPSHOT_ID
-f,--force    force deploy without prompting

Backup commands

Backup commands are only supported for ClearDB mySQL databases with paid plans.
ClearDB mySQL databases do not support snapshotting.

db:backup:list

List database backups

usage: bees db:backup:list [options] DATABASE_NAME

db:backup:create

Create a database backup

usage: bees db:backup:create [options] DATABASE_NAME

db:backup:restore
Restore a database backup

usage: bees db:backup:restore [options] DATABASE_NAME BACKUP_ID
-f,--force    force restore without prompting

 

Project commands

CloudBees project commands are only available for applications generated using the Bees wizard (on the web), built using the CloudBees SDK style.

Create application

Create a new web application using one of the predefined CloudBees application templates

usage: bees create [options] APP_NAME

Run application

Launch a local version of the CloudBees Tomcat 6 stack environment to run your application (runs on port 8080)

usage: bees run [options]
-p,--port <port>   server listen port (default: 8080)

If you'd like to attach to your running application with a debugger (such as Eclipse), you can use the beesd command instead, which will initialize the JVM process to support remote debuggers.

usage: beesd run [options]
-p,--port <port>   server listen port (default: 8080)

 

Running an existing WAR

Alternatively, if you have an existing WAR file created via your own build process, you can use the app:run command to launch a local CloudBees Tomcat 6 stack to run the WAR.

usage: bees app:run [options] WAR_Filename | WAR_directory
-e,--environment <environment>   environment configurations to load (default: run)
-p,--port <port>         server listen port (default: 8080)
-t,--tmpDir <tempdir>     the local working directory where temp files can be creates (default: 'tmp')--

Deploy application

Deploy the web application to the cloud

usage: bees deploy [options]
-a,--appid <appId>       application ID (of the form accountName/applicationName)
-e,--env <environment>   environment configurations to deploy
-m,--message <message>     message describing the deployment

If the specified appid does not exist, a new application environment will be created using this ID. If the appid already exists, and you have permission to update the application, the new application package will be published, and the existing application environment will be re-deployed to use the new package.

Note: If you accidentally overwrite an existing application or just want to rollback to the previous version, you can use the deployment history panel in the web-based application console to re-deploy a previous version of the application

Clean application

Removes all files generated by the compile and package commands

usage: bees clean

 

Compile application

Compiles all application source files

usage: bees compile

 

Configuration parameters commands

External configuration parameters can be defined for application and account with the bees:set|unset|update commands.

See the Configuration Parameters article for a complete list of commands.

Application Instances commands

The application instance commands (app:instance:cmd) allow finer grain control over application with multiple instances.

See the Application Instance Management article for a complete list of commands.

Application Snapshots commands

The application snapshot commands (app:snapshot:cmd) provide information about current and previous application snapshot deployments and allow deletion of non-active snapshots.  

See the Application Snapshot Management article for a complete list of commands.

Service Management commands

The service management commands provide a way to manage CloudBees services and eco-system addon services.

See the Service Management article for a complete list of commands.

Tags:
Created by Spike Washburn on 2011/07/01 08:00