CloudBees SDK
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.
unzip bees_sdk.zip
rm bees_sdk.zip
cd cloudbees-sdk-1.5.0
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 PATH=$PATH:$BEES_HOME
Refresh your terminal's bash session by executing
Alternate Installation for OSX
If you have the homebrew package manager, then simply run
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...
Verify your installation
Verify this is running properly by executing the "bees help" command
usage: bees <subcommand> [options] [args]
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.
app:deploy
Deploy a new version of an application using a WAR archive file
-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: small, medium, large, 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:delete
Delete an application
-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.
-a,--appid <appId> application ID
app:list
Returns the list of applications available to your account
-a,--account <arg> Account Name
app:restart
Restarts all deployed instances of an application
-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)
-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.
-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.
-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. You can update any 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)
-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
-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 |
app:resource:list
To list resources in your account (all apps, databases, session stores, SSL details etc)
-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.
db:create
Create a new MySQL database
-p,--password <password> Database password
-u,--username <username> Database username (must be unique)
db:delete
Delete a MySQL database
-f,--force forced delete without prompting
db:info
Returns information about connecting to a database
-p,--password print the database password info
db:list
Returns a list of all the databases associated with your account
-a,--account <arg> Account Name
db:set
Change your database password
-p,--password <password> The database password
db:snapshot:list
List database snapshots
db:snapshot:create
Create a database snapshot
-t,--title <arg> the database snapshot title
db:snapshot:delete
Delete a database snapshot
-f,--force force delete without prompting
db:snapshot:deploy
Deploy a database snapshot
-f,--force force deploy 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
Run application
Launch a local version of the CloudBees environment to run your application (runs on port 8080)
-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.
-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 server to run the WAR.
-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: 'temp')--
Deploy application
Deploy the web application to the cloud
-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
Compile application
Compiles all application source files
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.