Cloud 66 Toolbelt

Configuring Toolbelt

Installation

1. Download the cx executable to a directory in your PATH
2. Initialize it by running cx stacks list
3. Authenticate using your browser

For more detailed help on installation please refer to our Getting Started guide.

Installing on a server (headless)

To install Toolbelt on a server (without a browser):

1. Install and authenticate cx on your local machine (see above)
2. Log into your server via your terminal and move to the .cloud66 directory (under home)
3. Create a file named cx.json in that folder
4. Go to the terminal on your local machine, where you already have Toolbelt authorised and execute cx dump-token, which will give you your authorisation token
5. Copy this token and paste it into the (remote) cx.json file that you created in Step 3
6. Save the file and then run cx stacks list on the server to confirm that Toolbelt is initialised

Profiles for multiple account support

Toolbelt supports user with multiple Cloud 66 accounts via profiles.

Profile commands

cx config create NAME [arguments]
cx config use NAME
cx config rename OLD_NAME NEW_NAME
cx config delete NAME
cx config list
cx config show NAME
cx config update NAME [arguments]

Arguments

--org ORGANIZATION_NAME

The following arguments are used for Cloud 66 Enteprise

--client-id
--client-secret
--api-url
--base-url
--faye-endpoint

Usage

To set up a profile:

1. Run cx config create NAME where “name” is your chosen (arbitrary) profile name
2. Run cx config use NAME to switch to the new profile and initialize it by running cx stacks list
3. Authenticate using your browser (be sure to log into the correct account)

For more detailed help on installation please refer to our Getting Started guide.

Note

Switching between profiles

To switch between profiles, use cx config use NAME

All commands from that point onwards will run against the NAME profile. This is persisted between different terminal sessions until it’s changed.

Setting Profile per command

If you would like to run a command with a different profile other than the current profile, you can use the --profile argument with all commands:

cx --profile NAME stacks list

Using profiles with organizations

When you create a profile you can specify the organization to which this new profile should be linked. For example:

cx config create hobby --org my_private_sandbox

…will create a profile named “hobby” that is linked to a Cloud 66 organization named “my_private_sandbox”.

If you’re unsure about the name of an organization you can run the cx info command and looking at the Name field. You can also see this by logging into your Dashboard, visiting Account Settings and clicking on Organisations in the Account panel on the left.

About backup management

The following commands help you manage your backups, such as listing, downloading and initiating backups on your applications (stacks).

Note

List your backups

This will list all the managed backups of an application grouped by their database type and/or backup schedule.

Usage

$ cx backups list [-s <stack>] [-l] [<db type>]

Parameters

Example

$ cx backups list -s "My Awesome App" -e production

Download your backups

Allows you to download a managed database backup through the command line, concatenating separate files into one automatically if it consists of numerous files.

Usage

$ cx backups download [-s <stack>] [-d <download directory>] <backup id>

Parameters

Example

$ cx backups new -s mystack --dbtypes=postgresql --frequency="0 */1 * * *" --keep 50 --gzip=true exclude-tables=my_log_table --run-on-replica=false

Database management

Use these commands to configure your database servers.

Slave promotion to standalone master

Promotes the specified slave database server to a standalone master. The slave will be reconfigured as the new standalone DB. The existing master and other existing slaves will be orphaned, and will need to be removed, after which you can scale them up again.

Usage

cx databases promote-slave -s <stack> <slave server name>
cx databases promote-slave -s <stack> --dbtype=postgresql <slave server name>

Warning

The existing master and other slaves will need to be removed after this process as after this the new configuration will have only a single database. You will be able to configure replication from this again after that point.

In the case of any servers not being accessible during this time, those servers will remain unchanged. It is therefore important to stop/shutdown those servers in this case (or to manually stop the DB service on those servers) as having multiple masters in a cluster could cause problems throughout the cluster.

Resyncing Slave from Master

Re-syncs the specified slave database server with its master database server.

Usage

$ cx databases resync-slave [-s <stack>] <slave server name>

From time-to-time your slave database may go out of sync with its master. This action attempts to re-sync your specified slave server. This can happen depending on many factors (such as DB size, frequency of change, networking between servers etc).

The server provided must have already been configured as a replication slave via the Cloud 66 UI. Providing the database type is optional and is only necessary for shared servers where we can’t automatically determine the target database type.

Warning

Parameters

Example

$ cx databases resync-slave -s My_Awesome_App my_slave_server_name
$ cx databases resync-slave -s My_Awesome_App --dbtype postgresql my_slave_server_name

Download

Use this command to download a file from the remote server to your local computer.

Usage

$ cx download [-s <stack>] [--server <server name>] [source file] [target directory]

If you don’t specify a target directory, the file will be downloaded to your current local directory.

Parameters

Example

$ cx download -s "My Awesome App" --server web /tmp/file.txt /tmp/file.txt

Gateway management

These commands allow you to manage your gateways.

List gateways

This command lists all gateways on your account.

Usage

$ cx --org <organization_name> gateways list [ --verbose]

Parameters

Example

$ cx --org My_Awesome_org gateways add --name aws_bastion --address 1.1.1.1  --username ec2-user  --private-ip 2.2.2.2

Open gateway

Make the gateway available to use with cloud66 for ttl amount of time.

Usage

$ cx --org <organization_name> gateways open --name <gateway name> --key <The path to the gateway server key> --ttl <time to live >

Parameters

Example

$ cx --org My_Awesome_org gateways close --name aws_bastion

Remove gateway

This command will remove the gateway from your account

Usage

$ cx --org <organization_name> gateways remove --name <gateway name>

Parameters

Example

$ cx --org My_Awesome_org gateways remove --name aws_bastion

Job management

These commands allow you to list jobs and run a job immediately.

List jobs

This command lists all jobs on an application or a server.

Usage

$ cx jobs list [-s <stack>] --server <server name>|<server ip>|<server role> --service <service name>

Parameters

Examples

$ cx job run -s "My Awesome App" my_job
$ cx job run -s "My Awesome App" --arg "arg1" --arg "arg2" my_job

Temporary lease

Opens a port on your server firewall to temporarily allow access from a specified IP address.

Usage

$ cx lease [-s <stack>] [-f <from IP>] [-t <time to open>] [-p <port>]

Parameters

Example

$ cx lease -s "My Awesome App" -f 123.123.123.123 -t 30 -e production

For more fine grained access control, use the Application network settings page.

Cloud 66 Easy Login

Cloud 66 Toolbelt uses OAuth 2 for authentication and authorization. Once you have authorized Toolbelt with your Cloud 66 account you can create, delete, scale and deploy your stacks right from the terminal window. All these actions are accessible from the Cloud 66 web UI as well. As a matter of fact, Cloud 66 Toolbelt is more powerful than its web UI.

Cloud 66 Easy Login allows you to login to Cloud 66 web UI from your terminal without entering your password or 2fa. Once you have Cloud 66 Toolbelt authorized on your computer, simple use the login command to open up a browser and login to your account.

$ cx login

Access Control for Toolbelt Login

Account owners can control who on their teams can use the Toolbelt to login to their account. This is done through the permissions configurable on the Teams page for each user in the team.

Open your website

Usage

$ cx open [-s <stack>] [<server name>|<server ip>|<server role>]

Parameters

Example

$ cx open -s "My Awesome App"

Redeploy your application

This is an alias for the stacks redeploy command, which triggers the deployment of an application from the command line, just like clicking on redeploy in the UI.

Usage

$ cx redeploy [-s <stack>] [-y] [--git-ref <git_ref>] [--service <service>] [--service <service>] [--service <service>] [--deploy-strategy <strategy>] [--deployment-profile <profile name>]

Parameters

Examples

$ cx redeploy -s "My Awesome App" -e production --deploy-strategy fast

$ cx redeploy -s "My Awesome App" -e production -y --git-ref my_git_ref_value

$ cx redeploy -s "My Awesome Docker App" --service web:8c7f3d393162f88b8b9493f6babec574b03ca957 --service api:latest

Deploying an application that is already being deployed will enqueue your redeploy command and will run it immediately after the current deployment is finished.

Run command

This command will execute a command directly on the remote server. It does this by first opening the firewall for SSH from your IP address temporarily (20 minutes), downloads your SSH key if you don’t have it, starts a SSH session, executes the command specified and returns its output.

Usage

$ cx run -s <stack> --server <server name>|<server ip>|<server role> --service '<command>'

Parameters

At least one of the optional server parameters are necessary in order to identify which server to run the command on.

Example

$ cx run -s "My Awesome App" --server web1 'pwd'

Examples of service usage

The service parameter only applies to Maestro applications and allows you to enter a Docker container with your command (based on the latest image of that service).

• This command runs “ls -la” in a new container of the “webapp” service, returns the output, and exits:

  $ cx run -s mystack --svc webapp 'ls -la'
  

• This command runs “bundle exec rails c” in a new container of the “api” service, and remains in the session

  $ cx run -s mystack --service api --interactive 'bundle exec rails c'
  

• This command runs “bundle exec rails c” inside the specified container (web-123), and remains in the session.

  $ cx run -s mystack --container web-123 -i 'bundle exec rails c'
  

Server management

These commands allow you to list and set various settings on your servers.

List server settings

This command lists the possible settings for a specific server.

Usage

$ cx servers settings list [-s <stack>] --server <server name>|<server ip>|<server role>

Parameters

Examples

$ cx servers settings set -s "My Awesome App" --server lion

Reboot servers

Use this command to reboot a specific server from the command line

Usage

$ cx servers reboot [-s <stack>] [-e application environment] --server <server name> 

Parameters

Example

$ cx server reboot -s mystack --server lion -e production

Listing services

Usage

$ cx services list [-s <stack>] [--server <slave server name>|<slave server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Example

$ cx services scale -s mystack my_web_service 1
$ cx services scale -s mystack a_backend_service --server backend +5
$ cx services scale -s mystack a_backend_service -2
$ cx services scale -s mystack a_backend_service --group docker 3

Stopping services

Usage

$ cx services stop [-s <stack>] <service name> [--server <server name>|<server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Example

$ cx services restart -s mystack my_web_service
$ cx services restart -s mystack a_backend_service
$ cx services restart -s mystack --server my_server my_web_service

Getting service information

Usage

$ cx services info [-s <stack>] <service name> [--server <server name>|<server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Example

$ cx services info -s mystack my_web_service
$ cx services info -s mystack a_backend_service
$ cx services info -s mystack --server my_server my_web_service

Result

NAME             VALUE
name             web
source type      git
git-ref          d33e491e5a33
container count  1
image name       web
image uid        92fd690d33fe43f55c80dc6687a7171c
image tag        20150824122440373
command          bundle exec rails s production
build command    bundle exec rake db:schema:load
deploy command

List your application settings

Usage

$ cx settings list [-s <stack>] [-e <environment>]

Parameters

Example

$ cx settings set -s "My Awesome App" git.repository git://github.com/cloud66-samples/rails-mysql.git -e production

$ cx settings set -s my_stack deploy.parallel true

Settings Variables

These are the available settings:

• To enable, you can use the values 1, true, on or enable, and to disable you can use the values 0, false, off or disable

SSHing to your server

Allows direct SSH shell into your servers by opening the firewall temporarily for the source IP address, downloading the SSH key and starting a SSH session with one command.

Your server SSH key is downloaded to ~/.ssh and re-used in subsequent SSH connections via the toolbelt. You need to have shell to server rights over the application to use this command.

If your server deployed behind a bastion server, you need to provide the private key needed to connecting to bastion server to be able to connect to your server.

Usage

$ cx ssh  [--gateway-key <The path to the key of gateway server>]    [-s <stack>] <server name>|<server ip>|<server role>

Parameters

Example

$ cx ssh -s "My Awesome App" Lion -e production
$ cx ssh --gateway-key ~/.ssh/bastion_key  -s "My Awesome App" Lion -e production

List your stacks

Lists all the stacks available to your account.

Usage

$ cx stacks list [-e <environment>]

Parameters

Reboot your stacks

Reboot your application.

Usage

$ cx stacks reboot [-s <name of application>] [-y] [--group <group name>] [--strategy <serial or parallel>] [-e <environment>]

Parameters

The group parameter specifies which group of servers you wish to reboot. Valid values are “all”, “web”, “haproxy”, “db”; DB specific values like “mysql” or “redis” for example are also supported. If this value is left unspecified, the default value of “web” will be used

The strategy parameter specifies whether you want all your servers to be rebooted in parallel or in serial. Valid values for this parameter are “serial” or “parallel”; “serial” reboots involves web servers being removed/re-added to the LB one by one. Note that for this only applies to web servers; non-web server will still be rebooted in parallel. If this value is left unspecified, Cloud 66 will determine the best strategy based on your infrastructure layout.

Examples

$ cx stacks reboot -s mystack
$ cx stacks reboot -s mystack --group web
$ cx stacks reboot -s mystack --group all
$ cx stacks reboot -s mystack --strategy parallel
$ cx stacks reboot -s mystack --group web --strategy serial

Clear caches

For improved performance, volatile code caches exist for your application. It is possible for a those volatile caches to become invalid if you switch branches, change git repository URL, or rebase or force a commit. Since switching branch or changing git repository URL is done via the Cloud 66 interface, your volatile caches will automatically be purged. However, rebasing or forcing a commit doesn’t have any association with Cloud 66, so this command can be used to purge the exising volatile caches.

Usage

$ cx stacks clear-caches [-s <stack>]

Parameters

Example

$ cx stacks clear-caches -s "My Awesome App"

Manage your configuration files

List, download and upload of configuration files such as a service.yml or manifest.yml.

$ cx stacks configure list-versions [-f <filename>] [-s <stack>]
$ cx stacks configure download [-f <filename>] [-s <stack>]
$ cx stacks configure upload [-f <filename>] [-s <stack>]

Parameters

Examples

cx stacks configure download -f manifest.yml --stack my-maestro-cluster #downloads the Manifest file

cx stacks configure list-versions -f service.yml -s my-maestro-cluster #list the version history of your app's Service config file

Show help pages for a command

Shows a list of commands or help for one command.

Usage

$ cx stacks help [<command>]

Parameters

Tail

This will run a Linux tail command on the specified server and given log file. You must specify the log file name including the extension. If you don’t specify a path, or specify a relative path, then we will assume <stack-directory>/current/log (i.e. the subdirectory under the $STACK_PATH) as the “current” directory. You can specify a different (absolute) log path as needed.

This command is only supported on Linux and OS X.

Usage

$ cx tail [-s <stack>] <server name> <log filename> #Will use $STACK_PATH dir
$ cx tail [-s <stack>] <server ip>  /optional/log/path/<log filename>
$ cx tail [-s <stack>] <server role> /optional/log/path/<log filename>

Server names and roles are case insensitive and will work with their starting characters as well.

Parameters

A server parameter is required in order to identify which server to run the command on (i.e you must specify at least a server name, IP address or role).

Examples

$ cx tail [-s <stack>] <server name> <log filename> #Will use $STACK_PATH dir
$ cx tail [-s <stack>] <server ip>  /optional/log/path/<log filename>
$ cx tail [-s <stack>] <server role> /optional/log/path/<log filename>

List environment variables

This commands allows you to list environment variables for your application.

Parameters

Usage

$ cx env-vars list [-s <stack>] [--history] [environment_variables] 

Set environment variables

This command allows you to set (update) environment variables for your application.

Parameters

Usage

$ cx env-vars set My_Awesome_App FIRST_VAR=123

Download environment variables

This command downloads your env vars and writes them to a file. This file can either use the same format as web download (dotenv) or json.

You can specify which kinds of variables to download using environment-type with the following variables: all, which will return all environment variables; user, which will return only the user-created environment variables; generated, which will return Cloud 66 created environment variables; and locked, which will return non-editable Cloud 66 created environment variables.

Parameters

Usage

$ cx env-vars download -s mystack --file environment_variables_dotenv --file-type dotenv

$ cx env-vars download -s mystack --environment user --file environment_variables_json --file-type json

Upload environment variables

This command sets multiple environment variables for an application based on a file in either dotenv or json format.

You must specify an apply-strategy for your upload process. They can either be applied immediately or on the next deployment.

Warning

Parameters

Usage

$ cx env-vars upload -s mystack --file environment_variables_dotenv --file-type dotenv --apply-strategy deployment --delete

$ cx env-vars upload -s mystack --file environment_variables_json --file-type json --apply-strategy immediately

Listing processes

Usage

$ cx processes list [-s <stack>] [--server <server name>]

List all the processes running on an application or a server. Optionally provide the server to list only the processes running on that server.

Parameters

Example

$ cx processes scale -s mystack --server backend1 --name worker [+5]
$ cx processes scale -s mystack --server backend2 --name worker [-5]
$ cx processes scale -s mystack --server backend3 --name worker 15
$ cx processes scale -s mystack --name worker 2

Tunnel command

This command opens an SSH tunnel from your local machine to a remote server on the given ports. It does this by first opening the firewall for SSH from your IP address temporarily (20 minutes), downloads your SSH key if you don’t have it and opens an SSH tunnel.

Usage

$ cx tunnel -s <stack> --server <server name>|<server ip>|<server role> --remote <remote port> --local <local port>

Parameters

At least one of the optional server parameters are necessary in order to identify which server to run the command on.

Also, you need to specify at least the remote port. If local is missing, remote + 1 will be used as local. For example, --remote 3306 without local will use 3307 as local.

Examples

$ cx tunnel -s "My Awesome App" --server mysql --remote 3306 --local 13306

Upload

Use this command to copy a file from your local computer to the remote server.

Usage

$ cx upload [-s <stack>] [--server <server name>] [source file] [target directory]

If you don’t specify a target directory, the file will be uploaded to /tmp on your remote server.

Parameters

Example

$ cx upload -s "My Awesome App" --server web /tmp/file.txt /tmp/file.txt

List command

This command shows a list of all users you have access to. This is a list of all users within the organization you specify and have enough access rights to manage users for.

Usage

$ cx --org <organization_name> users list

Parameters

Examples

$ cx --org My_Awesome_org users show jim@gmail.com
$ cx --org My_Awesome_org users show jim@gmail.com --json /tmp/jim_profile.json

You can change the json file to suite any changes you require (or use it as it is) and apply it to other users in your account using the apply-profile command.

Note

You can download the same Access Profile from the web dashboard, under each user’s access rights page under the Teams left hand menu (click on the Accounts on top right to get there).

Apply Profile command

Apply Profile allows you to apply a user’s Access Profile to another one. To use this command you need to have an Access Profile as a json file. This can be generated using the users show command with the json option. Once you have the file you can modify it to make any changes you require in the Access Profile.

Usage

$ cx --org <organization_name> users apply-profile <username> --json <json_file_path> [--override]

Parameters

Examples

$ cx --org My_Awesome_org users apply-profile jack@gmail.com --json /tmp/jim_profile.json
$ cx --org My_Awesome_org users apply-profile jack@gmail.com --json /tmp/jim_profile.json --override

These will apply Jim’s profile to Jack’s; first one will append the access rights and the second one will overwrite them.

A note on overwriting Access Profiles

Any missing attribute for the json Access Profile will be left unchanged even if the override is used. Also, overrirde doesn’t have any effects on the contents of the account_profile section.

How to uninstall the toolbelt

If you need to uninstall the toolbelt you can simply delete the .cloud66 folder from your computer. If you’re not sure where it is, query your PATH and you will find it listed there.

Need help with deployments?

Contact Support

More Questions?

Join the Slack Channel