CLI

Every single action on SquareScale can be achieved or automated using the SquareScale command line. Here’s the information on how to use it.

Downloading the CLI

To download the CLI for your platform:

Check the version you’re running:

$ sqsc version
sqsc version 0.1.0 ("0303956")

Logging into SquareScale

To login to your SquareScale account, type the following:

$ sqsc login
GitHub login: myusername
GitHub password (typing will be hidden):
GitHub One Time Password (app): 424242
Forward GitHub authorization to Squarescale
Successfully authenticated as user myusername

Checking SquareScale account status

To check if you’re logged in or not, use the status option:

$ sqsc status
Squarescale endpoint: https://www.production.sqsc.squarely.io
◒ check authorization ... error
You're not logged in, please run login command

Once logged in, the output will be the following:

$ sqsc status
Squarescale endpoint: https://www.production.sqsc.squarely.io
◐ check authorization ... done
You're currently logged in

Creating a project

To create a new SquareScale HA project use the following:

$ sqsc project create -name "my-demo-app"
◒ create project ... done
[#3867] Created project 'my-demo-app'
[...]

To create a new SquareScale project in “single node” mode (development), use the following:

$ sqsc project create -infra-type "single-node" -name "my-demo-app-dev"
◐ create project ... done
[#3870] Created project 'my-demo-app-dev'
[...]

Listing projects

To list all the SquareScale projects running under the account, type in the following:

$ sqsc project list                                                                                                       [0/69]
◓ list projects ... done
Name            Status  Size
my-demo-app     ok      3/3

Deleting projects

To delete an existing SquareScale project, use the following:

$ sqsc project remove "my-demo-app-dev"
Destroy infrastructure and configuration for project my-demo-app-dev?
Enter the project name to destroy: my-demo-app-dev
◐ unprovision project ... done
◒ delete project ... done

Integrating Slack into a SquareScale project

It’s possible to send all notifications to a Slack channel, using a custom Slack hook. You can create a custom Slack hook at the following URL: https://<your_company>.slack.com/apps/manage/custom-integrations .

$ sqsc project slackbot <project name> <Slack Webhook URL>
$ sqsc project slackbot my-demo-app https://hooks.slack.com/services/S3GGT9DL4/F5GQS0492/zGmmu85aWKuOZ5UVKV6904fI
◐ change slack integration URL to https://hooks.slack.com/services/S3GGT9DL4/F5GQS0492/zGmmu85aWKuOZ5UVKV6904fI ... done
https://hooks.slack.com/services/S3GGT9DL4/F5GQS0492/zGmmu85aWKuOZ5UVKV6904fI

Here’s a sample SquareScale notification on a Slack channel:

_images/cli_add_slack.png

Adding a GitHub repository to a project

Our goal here is to add the GitHub repository available at https://github.com/sjourdan/hello to the SquareScale project named “my-demo-app”. Also, our project is simple and can be built only with the “internal” builder (a simple docker build).

The code from the repository, once built as a Docker image, will be available as a SquareScale service.

$ sqsc repository add -project "my-demo-app" -build-service internal -url https://github.com/sjourdan/hello
◓ add repository 'https://github.com/sjourdan/hello' to project 'my-demo-app' ... done
Successfully added repository 'https://github.com/sjourdan/hello' to project 'my-demo-app'

Listing GitHub repositories from a Project

To list the repositories added to a given SquareScale project:

$ sqsc repository list -project "my-demo-app"
◐ list repositories ... done
https://github.com/sjourdan/hello

Listing running services on a project

To list available services, their status, and the number of instances for each of them, type in the following:

$ sqsc container list -project "my-demo-app"
◐ list containers ... done
Type            Name            Status  Size    Web     Port
Repository      sjourdan/hello  running 3/3     false   80
PresetService   simple_builder  running 1/1     false   80

Adding a service using an existing Docker image

To add a preexisting Docker image as a service on SquareScale, like “wordpress:4” from the Docker Hub, use the following:

$ sqsc image add -project "my-demo-app" -name wordpress:4
◒ add docker image ... done
Successfully added docker image 'wordpress:4' to project 'my-demo-app'

Accessing details about a service

Lots of details are available about a SquareScale service using the show subcommand.

To show all information about the service named sjourdan/hello on the project my-demo-app, type in the following:

$ sqsc container show -project "my-demo-app" -name "sjourdan/hello"
◐ list containers ... done
Type:           Repository
Name:           sjourdan/hello
Status:         running
Size:           3/3
Pre Command:
Run Command:
Web:            false
Web Port:       80
Memory limit:   256 MB
CPU limit:      100 MHz
Network limit:  1 Mbps

Rebuild callbacks:
- https://www.production.sqsc.squarely.io/callbacks/containers/4cb67d564c0bb2153cef49984185fb55e04529b0/build

To be more specific and show only details about services running from external Docker images and not built from source:

$ sqsc container show -project "my-demo-app" -type "DockerImage"
◐ list containers ... done
Type:           DockerImage
Name:           wordpress:4
Status:         running
Size:           3/3
Pre Command:
Run Command:
Web:            false
Web Port:       80
Memory limit:   256 MB
CPU limit:      100 MHz
Network limit:  1 Mbps

Refresh callbacks:
- https://www.production.sqsc.squarely.io/callbacks/containers/59b26a567e886ecbc8571716975bcbf804d938b6/refresh

Accessing a service by its DNS name

All services are reachable by their DNS name, through the service discovery system (Consul).

For example, the main RDBMS is always reachable using the db.service.consul name.

If the service is named “wordpress:4”, then it will be available using the wordpress-4.service.consul name.

If the service is named “johndoe/myrepo”, then it will be available using the johndoe-myrepo.service.consul name.

Scaling up & down the number of instances of a service

If you want to scale up or down and change the number of instances of a given service (sjourdan/hello in this example), you can set it using sqsc container set:

$ sqsc container set -project "my-demo-app" -container "sjourdan/hello" -instances 2
◑ configure container ... done
Successfully configured container 'sjourdan/hello' for project 'my-demo-app'

Warning: if your service exports a static port, the maximum number of instances of the service will be equal to the number of nodes in the cluster. In the case of a backend service or a worker without exposed port, there’s no limit.

Setting a memory constraint on a service

It’s easy to mitigate memory leaks consequences or optimize memory usage of a service, using sqsc container set. Whether you’re interested in minimizing the memory usage of your service, or imposing a high memory reservation for an important service, you can use the following (in this case qe impose a memory limit of 128MB for each instance):

$ sqsc container set -project "my-demo-app" -container "sjourdan/hello" -memory 128
◒ configure container ... done
Successfully configured container 'sjourdan/hello' for project 'my-demo-app'

Overriding the command or arguments of a service

To override the default container command or its arguments (wether the Dockerfile uses a CMD or an ENTRYPOINT), use the following:

$ sqsc container set -project "my-demo-app" -container "sjourdan/hello" -command "--debug=true"
◒ configure container ... done
Successfully configured container 'sjourdan/hello' for project 'my-demo-app'

Now the sjourdan/hello service will run with the --debug=true argument until you remove it.

Displaying the load balancer URL for a project

To know what’s the easy URL where the project is available, use the following:

$ sqsc lb url -project "my-demo-app"
◑ project url ... done
Project 'my-demo-app' is available at http://www.production.my-demo-app.squarely.io

Setting a service behind the public HTTP Load Balancer

To set a service to be served behind the public load balancer, in our case, the “sjourdan/hello” service listening on port 80, from the “my-demo-app” project:

$ sqsc lb set -container "sjourdan/hello" -port 80 -project "my-demo-app"
◑ configure load balancer ... done
[#3881] Successfully configured load balancer (enabled = 'true', container = 'sjourdan/hello', port = '80') for project 'my-demo-app'wait for load balancer change ... done
done

Now you can access the service from the public project URL. To know it, see Displaying the load balancer URL for a project.

Showing the Load Balancer configuration for a project

To show the load balancer configuration for a project (“my-demo-app”), and see which service is served, use the following:

$ sqsc lb list -project "my-demo-app"
◒ list load balancer config ... done
state: enabled ([] -> maps to <container>:<port>, no mapping otherwise)

Displaying
[] sjourdan/hello:80
[ ] wordpress:4:80
[ ] simple_builder:80

Enabling HTTPS on the Load Balancer for your project

To enable HTTPS on the load balancer, your need the certificate files from your SSL provider.

In our case, the certificate file is named my_ssl_cert.cert, the private key is named my_ssl_key.key. Optionaly a certificate chain can also be uploaded using the option -cert-chain.

$ sqsc lb set -project "my-demo-app" -container "sjourdan/hello" -https -cert my_ssl_cert.cert -secret-key my_ssl_key.key
◒ configure load balancer ... done
[#3886] Successfully configured load balancer (enabled = 'true', container = 'sjourdan/hello', port = '80') for project 'my-demo-app'wait for load balancer change ... done
done

Your project is now served using HTTPS!

Scaling the cluster size

The default HA cluster includes 3 nodes, but it’s possible to add or remove nodes on-demand, to scale up or down.

To set the cluster size to 4 instead of 3:

$ sqsc cluster set -project "my-demo-app" -size 4
Changing cluster settings for project 'my-demo-app' may cause a downtime.
Is this ok? [y/N] y
◒ change cluster size ... done
[#3892] changed cluster size from 3 to 4wait for cluster change ... done
done

Streaming the logs

To stream (and follow) the logs of the project using the command line:

$ sqsc logs -project "my-demo-app" -f
◓ last logs for project 'my-demo-app' ... done

It’s also possible to stream the logs from only one service:

$ sqsc logs -project "my-demo-app" -container "sjourdan/hello" -f
◒ last logs for container 'sjourdan/hello' ... done

Listing available database engines and sizes

SquareScale proposes multiple options for the database engine (DBMS). To list them all:

$ sqsc db list
◒ list available database engines and sizes ... done
Available engines

  mariadb
  MySQL
  postgres

Available sizes

  Single Node infrastructure
    dev
  High Availability infrastructure
    small
    medium
    large

Showing the current database engine configuration

To know what DBMS engine or size a project is using, use the db show subcommand:

$ sqsc db show -project "my-demo-app"
◓ fetch database configuration ... done
DB enabled:             true
DB Engine:              postgres
DB Size:                small

Scaling the DBMS

Warning: this action triggers a server change that will render the DBMS unavailable for a few minutes.

To scale up or down a single DBMS instance, simply set the required size (see available sizes at Listing available database engines and sizes.) :

$ sqsc db set -project "my-demo-app" -size medium
Changing cluster settings for project 'my-demo-app' will cause a downtime.
Is this ok? [y/N] y
◐ scale project database ... done
[#3899] Successfully set database for project 'my-demo-app': medium postgreswait for database change ... done
done

Changing the DBMS engine

Warning: this action triggers a server change that will cause the DBMS to be unavailable for a few minutes.

A number of DBMS engines are available (see Listing available database engines and sizes.)

To change the managed DBMS in use, and in this case, switch to a MariaDB DBMS on a small instance:

$ sqsc db set -project "my-demo-app" -size small -engine "mariadb"
Changing cluster settings for project 'my-demo-app' will cause a downtime.
Is this ok? [y/N] y
◓ scale project database ... done
[#3908] Successfully set database for project 'my-demo-app': small mariadbwait for database change ... done
done

Listing environment variables

You can display all the environment variables for a given SquareScale project:

$ sqsc env get -project "my-demo-app" -all
◑ list environment variables ... done
Project
  DB_HOST             = db-my-demo-app-production.cvnzekqpf90m.eu-west-1.rds.amazonaws.com
  DB_PORT             = 3306
  PROJECT_DB_USERNAME = dbadmin
  PROJECT_DB_PASSWORD = BitC7VCknpLzs3_RBArNTgkUgPDQK7-d
  DB_ENGINE           = mariadb
  DB_NAME             = dbproduction
  DB_PASSWORD         = BitC7VCknpLzs3_RBArNTgkUgPDQK7-d
  DB_USERNAME         = dbadmin
  PROJECT_DB_NAME     = dbproduction
wordpress:4
  DB_HOST             = db-my-demo-app-production.cvnzekqpf90m.eu-west-1.rds.amazonaws.com
  DB_PORT             = 3306
  PROJECT_DB_USERNAME = dbadmin
  PROJECT_DB_PASSWORD = BitC7VCknpLzs3_RBArNTgkUgPDQK7-d
  DB_ENGINE           = mariadb
  DB_NAME             = db_msik5v
  DB_PASSWORD         = 8ZzWxlTS4S3YzxoN301fy-3TLuIY2C4mCVWpAxvn0-E=
  DB_USERNAME         = db_msik5v_user
  PROJECT_DB_NAME     = dbproduction
  SQSC_SERVICE_NAME   = wordpress-4
[...]

It’s possible to list only global environment variables:

$ sqsc env get -project "my-demo-app"
◒ list environment variables ... done
DB_NAME=dbproduction
DB_PORT=3306
PROJECT_DB_NAME=dbproduction
DB_ENGINE=mariadb
DB_HOST=db-my-demo-app-production.cvnzekqpf90m.eu-west-1.rds.amazonaws.com
DB_PASSWORD=BitC7VCknpLzs3_RBArNTgkUgPDQK7-d
DB_USERNAME=dbadmin
PROJECT_DB_USERNAME=dbadmin
PROJECT_DB_PASSWORD=BitC7VCknpLzs3_RBArNTgkUgPDQK7-d

You can also display environment variables for a single service of the project:

$ sqsc env get -project "my-demo-app" -container "wordpress:4"
◒ list environment variables ... done
DB_HOST=db-my-demo-app-production.cvnzekqpf90m.eu-west-1.rds.amazonaws.com
DB_ENGINE=mariadb
DB_PASSWORD=8ZzWxlTS4S3YzxoN301fy-3TLuIY2C4mCVWpAxvn0-E=
DB_PORT=3306
DB_USERNAME=db_msik5v_user
PROJECT_DB_NAME=dbproduction
PROJECT_DB_USERNAME=dbadmin
PROJECT_DB_PASSWORD=BitC7VCknpLzs3_RBArNTgkUgPDQK7-d
DB_NAME=db_msik5v
SQSC_SERVICE_NAME=wordpress-4

Finally, you can display the value of a specific variable:

$ sqsc env get -project "my-demo-app" DB_NAME
◒ list environment variables ... done
dbproduction
$ sqsc env get -project "my-demo-app" -container "wordpress:4" DB_NAME
◑ list environment variables ... done
db_msik5v

Setting environment variables

To manually set environment variables for a single service, use the env set subcommand:

$ sqsc env set -project "my-demo-app" -container "wordpress:4" WORDPRESS_DB_HOST db.service.consul
◓ set environment variable ... done
Successfully set variable 'WORDPRESS_DB_HOST' to value 'db.service.consul' for container 'wordpress:4'

To set a global environment variable for the whole project, don’t use the -container flag:

$ sqsc env set -project "my-demo-app" APP_NAME MyCustomerID
◒ set environment variable ... done
Successfully set global variable 'APP_NAME' to value 'MyCustomerID'

Don’t forget to confirm the environment variables are available using Listing environment variables.

Removing environment variables

To manually remove an environment variable (WORDPRESS_DB_USER) for a single service (wordpress:4), use the following:

$ sqsc env set -project "my-demo-app" -container "wordpress:4" -remove WORDPRESS_DB_USER
◐ set environment variable ... done
Successfully removed variable 'WORDPRESS_DB_USER' for container 'wordpress:4'

You can only remove variables you added yourself or overridded.