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

Running Toolbelt inside a Docker container

You can run the Cloud 66 Toolbelt inside a Docker container, although this is not officially supported.

Step 1: Start an ubuntu container

We start a generic Ubuntu container (Cloud 66 runs on Ubuntu servers)

$ docker run -it ubuntu:latest /bin/bash

Step 2: Install required/useful tools

Toolbelt relies on three tools - curl, nano and ssh - so we install these packages.

$ apt update

$ apt install curl nano ssh -y

Step 3: Create some default folders

We need to create some default folders to support Toolbelt’s requirements.

$ mkdir -p ~/.ssh

$ mkdir -p ~/.cloud66

Step 4: Install Toolbelt

Now we install the Toolbelt by CURLing the installation shell script on S3:

$ curl -sSL https://s3.amazonaws.com/downloads.cloud66.com/cx_installation/cx_install.sh | bash

Step 5: Register Toolbelt

Finally we need to register Toolbelt:

1. Install and authenticate cx on your local machine
2. SSH into your container 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 (container’s) cx.json file that you created in Step 3
6. Save the file and then run cx stacks list from inside the container to confirm that Toolbelt is initialised

After this, you should be able to use cx commands inside the container.

Shortcuts

Toolbelt has some useful shortcuts to help speed up your workflow.

Running cx in a git directory

To make life easier for you, the Cloud 66 toolbelt detects the Git URL and branch for each directory it is run in. As such, you won’t have to specify which application you want to run the toolbelt on if you’re in the git folder and branch of one of your applications.

Naming shortcuts

We apply naming shortcuts to both application and server names, as well as server roles in the toolbelt, so you don’t have to type their full names. We just need you to type enough of a name for it to be unique.

For example, if you only have one application that starts with m, you can simply type m. Similarly, if you only have one web server, you can type w instead of web

Toolbelt commands

These commands are listed alphabetically by top level command name.

backups list

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

$ cx backups list --stack <application name> --latest 

backups download

Download a managed database backup via the command line. If the backup spans multiple files, the command will automatically concatenate them into a single file.

$ cx backups download --stack <application name> [--download <download directory>] <backup id>

backups new

Creates a new database backup task for an application.

cx backups new --stack <application name> --dbtypes postgresql --frequency <schedule> --gzip <bool> --exclude-tables <table name> --run-on-replica <bool> --backup-type <type>

config

Allows you to configure multiple profiles in cx to support multiple Cloud 66 accounts.

containers list

Alias: container list

Lists all the containers running on an application or server (depending on your parameters).

$ cx containers list --stack <application name> [--server <server name>][--environment <environment name>][--verbose]

containers attach

Alias: container attach

Connect to a container (by container name) and print the STDOUT output stream of the container process. This is roughly equivalent to tailing the logs of a container.

If you need to connect to a container in order to execute commands, you should use the cx run command and specify the name of the container.

$ cx containers attach --stack <application name> <container ID>

containers stop

Alias: container stop

Stops a specific container on a given stack by container ID or name (supports partial IDs and names).

$ cx containers stop --stack <application name> <container ID>|<container name>

containers restart

Alias: container restart

Restarts a particular container on a given stack by container ID or name (supports partial IDs and names).

$ cx containers restart --stack <application name> <container ID>|<container name>

databases promote-replica

Alias: database promote-replica Alias: database promote-slave (deprecated) Alias: databases promote-slave (deprecated)

Promotes the specified replica database server to a standalone master. The replica will be reconfigured as the new standalone DB. Providing the database type is optional and is only necessary for shared servers where we can’t automatically determine the target database type.

The existing master and other replicas 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 again by scaling up new servers.

In the case of any servers not being accessible during this time, those servers will remain unchanged. It is therefore important to stop/shut down 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.

$ cx databases promote-replica --stack <stack name> [--dbtype <database type>] <replica server name>

databases resync-replica

Alias: database resync-replica Alias: database resync-slave (deprecated) Alias: databases resync-slave (deprecated)

Re-syncs the specified replica database server with its master database server. From time-to-time your replica database may go out of sync with its master. This action attempts to re-sync your specified replica 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 replica 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.

$ cx databases resync-replica --stack <application name> --dbtype <database type> <replica server name>

download

Use this command to download a copy of file from the remote server to your local computer. If you don’t specify a target directory, the file will be downloaded to your current local directory.

$ cx download --stack <application name> --server <server name> <path to source file> [<target directory>]

dump-token

Prints the content of the cx token file with no new lines.

Usage

$ cx dump-token

env-vars list

Prints environment variables (both keys and values) for your application to terminal. If environment variable keys are specified, the list will be limited to those keys. The --history option lists any recent changes to each variable.

$ cx env-vars list --stack <application name> <environment variables> [--history]

env-vars download

Downloads the environment variables from an application 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 returns all environment variables
• user returns user-created environment variables
• generated returns environment variables generated by Cloud 66
• locked returns non-editable environment variables that were generated by Cloud 66

$ cx env-vars download --stack <application name> --environment-type <type> --file <filename> --file-type <file-type>

env-vars set

Adds (or updates) a single environment variables for your application. You can use the --apply-strategy option to specify when Cloud 66 will apply the change in environment variables to your servers. The default is immediately.

$ cx env-vars set --stack <application name> [--apply-strategy] <key> <value> 

env-vars upload

Set the 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.

$ cx env-vars upload --stack <application name> --file <filename> --file-type <type> [--apply-strategy <strategy>] [--delete]

failover-groups list

Lists the Failover Groups for a Cloud 66 account. Info includes the Failover Group ID, address, attached applications and current active application.

$ cx failover-groups list [--output <view>]

failover-groups add

Adds a new Failover Group to a Cloud 66 account. You can create an empty Failover Group with neither primary nor secondary app set.

$ cx failover-group add [--primary <primary app>] [--secondary <secondary app>] [--current <current app>] [--no-primary] [--no-secondary]

failover-groups delete

Deletes an existing Failover Group from a Cloud 66 account.

$ cx failover-groups delete --uid <failover UID>

failover-groups update

Updates an existing Failover Group on a Cloud 66 account.

$ cx failover-group update --uid <failover UID> [--primary <primary app>] [--secondary <secondary app>] [--current <app pointer>] [--no-primary] [--no-secondary]

help

Shows a full list of commands or detailed help for one command.

Usage

$ cx help
$ cx <command> --help

info

Shows information about your account, toolbelt and the specified stack or the current directory.

$ cx info --stack <application name --unmanaged

init

Initializes the Toolbelt.

init agent

Initializes the Toolbelt as a standalone (headless) agent.

jobs list

Alias: job list

Lists all automated (scheduled) jobs on an application or a server.

$ cx jobs list --stack <application name> --server <server name>|<server ip>|<server role> --service <service name>

jobs run

Alias: job run

Runs the given job once with the given parameters.

$ cx jobs run --stack <application name> --arg [--arg option --arg option] <job name>

lease

This will open the firewall of the given server for a limited time. 'Time to open' is in minutes. By default the firewall closes after 20 minutes. The maximum time to open is 240 minutes.

$ cx lease --stack <application name> --port <port to open> [--from <from IP>] --tto <lease time>

login

Opens the default web browser and logs into the associated Cloud 66 account. This makes it easier to login to Cloud 66 web UI by streamlining your login through a registered and authenticated Toolbelt.

Usage

$ cx login

notifications download

Download all the alert settings for a given application as a YAML formatted file.

$ cx notifications download --stack <application name> --file <filename>

notifications upload

Uploads notifications in a YAML formatted file. Settings in the file will replace any existing settings. If an application group is specified, all of the apps in the group will be updated.

$ cx notifications upload [--stack <application name> | --application-group <group name>] --file <filename>

open

Opens the default web browser and opens the web end-point of a given application.

$ cx open --stack <application name> <server name>

processes list

Alias: process list

List the details of the processes running on an application or a server.

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

processes pause

Alias: process pause

Pauses all processes for the given service and/or server.

$ cx processes pause --stack <application name> [--server <server name>] [<process name>]

processes restart

Alias: process restart

Restarts all processes on the given service and/or server.

$ cx processes restart --stack <application name> [--server <server name>] [<process name>]

processes resume

Alias: process resume

Resumes all paused processes on the given service and/or server.

$ cx processes resume --stack <application name> [--server <server name>] <process name>

processes scale

Alias: process scale

Starts <count> processes from the given process definition. <count> can be an absolute value like 2 or a relative value like [+2] or [-3] If server is provided, will start <count> processes on that server. If server is not provided, will start <count> processes on every server. NOTE: the square brackets are required for relative count values.

$ cx processes scale --stack <application name> [--server <server name>] [--name <process name>] [<count>]

redeploy

Alias: stacks redeploy

Enqueues redeployment of an existing application. If the app is already building, another build will be enqueued and performed immediately after the current one is finished.

$ cx redeploy --stack <application name> --listen [-y] [--git-ref <git_ref>] [--service <service>] [--deploy-strategy <strategy>] [--rollout-strategy <strategy>] [--canary-percentage <percentage>] [--deployment-profile <profile name>]

register-server

A shortcut to run the server registration script on a group of servers.

$ cx register-server [--org <organization>] [--server <IP address>] [--file <filename.txt>] [--user <username>] [--key <private SSH key>] [--force-local-ip <bool>] [--tags <tagA,tagB>]

run

Execute a command directly on a remote server, in a service, or in a existing container. To do this it:

1. Opens the firewall for SSH from your IP address temporarily (20 minutes)
2. Starts a SSH session
3. Executes the command specified and returns its output.

You need to add your public (local) SSH key to your Cloud 66 account before running this command. You also need to have “shell to server” rights on the application to use this command.

You can use either the server name (e.g. lion) or the server IP (e.g. 123.123.123.123) or the server role (e.g. web). If a role is specified the command will connect to the first server with that role.

This command is only supported on Linux and OS X clients (for Windows you can run this in a virtual machine if necessary)

$ cx run --stack <application name> [--server <server name> | <IP address>] [--service <service name>] [--container <container name>] [--interactive] '<commands>'

servers list

Alias: server list

List details for all the servers used by an application including name, IP address, server role and the date/time it was created. The <name> argument can be a list of server names entered as separate parameters. The optional <columns> argument sets the type of server info to display in each column, and their order.

Column options: availability-zone, cores, created-at, distro, distro-version, dns, health, is-kubernetes-master, memory, name, notifications, private-ip, product-uuid, public-ip, region, roles, root-disk-size, root-disk-type, subnet-id, uid, vendor-uid, vpc-id

$ cx servers list --stack <application name> --columns="<list of columns, comma separated>" <server name>

servers reboot

Alias: server reboot

Reboot a specific server.

$ cx servers reboot --stack <application name> --server <server name>

servers settings list

Alias: server settings list

Lists all the settings applicable to the given server. It also shows the key, value and the readonly flag for each setting. Settings can be a list of multiple <setting> arguments. To change each server setting, use the server-set command.

$ cx servers settings list --stack <application name> --server <server name> <setting>

services info

Alias: service info

Get info for given the service. The list of available services can be obtained through the services list command. If the server is provided it will only query the specified server.

$ cx services info --stack <application name> [--server <server name>] <service name> 

services list

Alias: service list

List all the services and running containers of a whole application or a specific server.

$ cx services list --stack <application name> [--server <server name>] [<service name>]

services pause

Alias: service pause

Pauses all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

$ cx services pause --stack <application name> [--server <server name>] <service name>

services restart

Alias: service restart

Restarts all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

$ cx services restart --stack <application name> [--server <server name>] <service name>

services resume

Alias: service resume

Resumes all the containers from the given service that were previously paused. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

$ cx services resume --stack <application name> [--server <server name>] <service name>

services scale

Alias: service scale

Starts <count> containers for the given service across the stack. If <count> is an absolute value like 2, then that will be the total of <count> containers across the application. If <count> is a relative value like [+2] or [-3], then the current total count of containers across the application will be changed by <count>. NOTE: the square brackets are required for relative count values.

$ cx services scale --stack <application name> <service name> <count>

services stop

Alias: service stop

Stops all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

$ cx services stop --stack <application name> [--server <server name>] <service name>

settings list

Alias: setting list

Lists all the settings for the given application, including the key, value and readonly flag for each setting. You can use <setting> multiples times to query multiple services.

$ cx settings list --stack <application name> <setting>

settings set

Alias: setting set

Sets and applies the value of a setting to an application.

$ cx settings set --stack <application name> <setting> <values>

Available settings

ssh

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

You need to add your public (local) SSH key to your Cloud 66 account before running this command. You also need to have “shell to server” rights on the application to use this command.

$ cx ssh  [--gateway-key <path to gateway key>] --stack <application name> <server name>|<server ip>|<server role> --vv [-i <your private key>]

ssh-config

Displays and/or sets the public key associated with your Cloud 66 account.

$ cx ssh-config get-public-key
$ cx ssh-config set-public-key --public-key "<full contents of public SSH key file>"

stacks clear-caches

Alias: stack clear-caches

For improved performance, Cloud 66 caches volatile code. It is possible for a those caches to become invalid if you switch branches, change git repository URL, 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 is external to Cloud 66 and therefore doesn’t trigger the purge, so this command can be used to manually purge the existing volatile caches.

$ cx stacks clear-caches --stack <application name>

stacks configure download

Alias: stack configure download

Download configuration files such as a service.yml or manifest.yml. (containerized apps only)

$ cx stacks configure download --file <filename> --stack <application name> --output <output path>

stacks configure list-versions

Alias: stack configure list-versions

List the versions of configuration files such as a service.yml or manifest.yml. (containerized apps only)

$ cx stacks configure list-versions --file <filename> --stack <application name> --version <file version type>

stacks configure upload

Alias: stack configure upload

Upload configuration files such as a service.yml or manifest.yml. (containerized apps only)

$ cx stacks configure upload --file <filename> --stack <application name> --comments <comment>

stacks configuration list

Alias: stack configuration list

List all the available configurations on an application.

$ cx stacks configuration list --stack <application name>

stacks configuration apply

Alias: stack configuration apply

Applies the latest configuration to an application. You can find all the types of configuration available on your application using the stacks configuration list function.

$ cx stacks configuration apply --stack <application name> --type <config type>

stacks configuration download

Alias: stack configuration download

Gets the content of the specified configuration file from the given application and either prints it to screen or saves it as a file. You can find all the types of configuration available on your application using the stacks configuration list function.

$ cx stacks configuration download --stack <application name> --type <config type> --output <filename>

stacks configuration upload

Alias: stack configuration upload

Updates the content of the specified configuration type on the stack and (optionally) applies it. You can find all the types of configuration available on your application using the stacks configuration list function.

$ cx stacks configuration upload --stack <application name> --type <config type> --source <source file> --no-apply --commit-message <message>

stacks list

Alias: stack list

Lists applications. Shows the application name, environment, and last deploy time. You can query (multiple) applications by name - but the command will display all applications by default.

$ cx stacks list [<application name>] [--output <output style>]

stacks create

Alias: stack create

Creates a new Cloud 66 application based on a service definition (service.yml) and an optional application Manifest (manifest.yml).

$ cx stacks create --name <new application name> --service_yaml <service definition>

stacks listen

Alias: stack listen

Acts like a tail for all the deployment logs for an application (to tail a specific log file, see the function below).

$ cx stacks listen --stack <application name>

stacks reboot

Alias: stack reboot

Reboots groups of servers in your application. Valid values for the <group> argument are all, web, haproxy, and db. Database specific values like mysql or redis are also supported.

<strategy> specifies whether you want your web servers to be rebooted in parallel or in serial. For serial reboots web servers are removed and re-added to the load balancer one by one. Non-web server will always be rebooted in parallel. If this value is left unspecified, Cloud 66 will determine the best strategy based on your infrastructure layout.

$ cx stacks reboot --stack <application name> --group <server group> --strategy <reboot strategy> -y

stacks redeploy

Alias: stack redeploy

Triggers the deployment of an application. Alias of redeploy function.

stacks restart

Alias: stack restart

Sends a restart signal to all application components. This means different things for different components. For a web server, it means a restart of nginx. For an application server, this might be a restart of the worker processes.

$ cx stacks restart --stack <application name>

stacks ssl

Alias: stack ssl

Add an SSL certificate to a stack.

$ cx stacks ssl --stack <application name> --type <certificate type> --domain <domain name> --ssl-termination --cert <certificate file> --key <SSL key file> --intermediate <intermediate cert file> --overwrite

tags add

Add tags to a given entity.

$ cx tags add --entity <entity type> --id <entity ID> --tags <tag>

tags delete

Remove tags from a given entity.

$ cx tags delete --entity <entity type> --id <entity ID> --tags <tag>

tail

Runs 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 und $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.

$ cx tail --stack <application name> <server name> | <server ip> | <server role> /optional/log/path/<log filename>

test

Checks if cx is properly installed and authenticated.

Usage:

$ cx test

tunnel

Opens an SSH tunnel between your local machine and the remote server on a specific port. This is useful when connecting to remote databases or other services using local tools.

tunnel does the following:

1. Opens a lease in port 22 for your local IP address
2. Fetches your SSH key from your Cloud 66 account
3. Starts an SSH tunnel between your machine and the server on the given ports
4. Closes the tunnel when you exit the Toolbelt (Ctrl-C)

If a role is specified the command will connect to the first server with that role.

To specify the ports for the tunnel, use --local and --remote arguments. For example, if you need to connect to a MySQL server, you can use 3307 locally and 3306 (MySQL port on the server) as the remote port. Once the tunnel is established, you can use your favourite MySQL client to connect to the server on 127.0.0.1 and the local port (3307 in this case).

If a local port is not specified, cx will use "remote + 1" as a convention for the local port. For example, if you only specify --remote 5432 without explicitly specifying local, cx will use 5433 as the local port.

This command is only supported on Linux and OS X (for Windows you can run this in a virtual machine if necessary)

$ cx tunnel --stack <application name> --server <server name> | <server IP> | <server role> --local <local port> --remote <remote port>

update

This command runs automatically. You should not need to run it manually. You can use it to force cx to use a certain version.

Usage:

$ cx update --force <version>

upload

Copies a file from your local computer to the remote server. Uploads the files to the /tmp directory by default, unless a path is specified.

This command open the firewall for SSH from your IP address temporarily (20 minutes) and starts a SSH session. If a role is specified the command will connect to the first server with that role.

You need to add your public (local) SSH key to your Cloud 66 account before running this command. You also need to have “shell to server” rights on the application to use this command.

This command is only supported on Linux and OS X (for Windows you can run this in a virtual machine if necessary)

$ cx upload --stack <application name> --server <server name> | <server IP> | <server role> /path/to/source/file /path/to/target/directory

users list

Shows a list of all the users in an organization that you have rights to manage. You can find your <organization name> by using cx info.

$ cx --org <organization name> users list

users apply-profile

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.

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

$ cx users apply-profile <user email> --json <access profile>

users show

Returns details about a user. You can dump these as a json file for use with the users apply-profile function.

$ cx users show <user email> --json <filename>

Configuration profile commands

You can configure your Toolbelt to work with multiple Cloud 66 accounts and/or organizations using configuration profiles.

config create

Creates a new configuration profile

$ cx config create <name> [--org <org name>]

config use

Switches to using the named configuration profile.

$ cx config use <name>

config rename

Renames an existing configuration profile.

$ cx config rename <old name> <new name>

config delete

Delete a configuration profile.

$ cx config delete <name>

config list

Lists all your configuration profiles.

$ cx config list

config show

Show the details for a profile

$ cx config show <name>

config update

Set a configuration profile to point to an organization.

cx config update NAME [--org <org name>]

Setting up a profile:

1. Run cx config create <name> where <name> is your chosen 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.

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.