Exploring the Corus Command-Line

You've had quite a good overview of the Corus CLI in the introductory tutorial. Now it's time for a more in-depth look.

The CLI provides an array of commands, used to manage distributions, processes, and Corus itself.

In this section, we're presenting you with the CLI's main features.

A Note on the Architecture

The command-line is just a front-end that itself wraps usage of the remote interface provided by the Corus server, allowing it to be managed over the network.

In fact, the CLI internally uses a "facade" that hides the details of using the remote interface. One could use the facade to implement their own management frontend, for example.

Through the facade, the CLI connects to a Corus server over the network. The commands that are typed at the command-line are converted to object form - in fact, to remote method calls that are processed by Corus.

Obtaining On-line Documentation

The CLI supports an array of commands. A lot of these commands will look familiar to you since they mimick the Linux/Unix ones.

This characteristic is intentional: it was one of our main goals to get sysadmins up and running rapidly, since they're the ones making the deployments in production. It is our experience that after getting used to Corus, you'll type common Linux commands in the CLI and wonder why they're not working, then realizing that you're indeed using the CLI...

The most basic and important command is man, which, as in Linux/Unix, allows displaying help about a specific command. Just typing man without any arguments will display the categorized list of commands. To obtain help about a specific command, type man followed by the actual name of the command whose help you want displayed.

You'll see that the help not only documents the syntax of a command, but also provides examples illustrating different scenarios. To obtain details about a command, the online help is your best friend.

Experimenting

For the sake of practice, we'll go through the deployment of your Grails web app again, and explore the CLI in a more in-depth manner.

As a first step, start a Corus instance on your workstation. Then connect to it with the CLI (note that the options for the host and port are not required when connecting to localhost, on the default Corus port):

coruscli -h localhost -p 33000

Now deploy the distribution:

deploy target/corus_sample_jetty-develop-basic.zip

As you've seen previously, you can use ls to view the list of currently deployed distributions. The ls command also takes options that allow filtering the results (in cases where you have many distributions with different names and/or versions). Type man ls to view the options that the command takes.

Of course there's only one distribution deployed now, so there's not much to filter. But just for the sake of showing that it works, type the following as is:

ls -d foo

No distribution is listed, confirming that the filtering works... Now type:

ls -d basic-sample-jetty -v 5.0

Nothing again: no basic-sample-jetty version matches the one specified.

Now this:

ls -d basic-sample-jetty -v 1.0

Our distribution appears.

As you've seen in the Grails web app tutorial, the exec command also takes such options. For example:

exec -d basic-sample-jetty -v 1.0 -v 1.0 -n server -p dev

The above starts the process corresponding to the given options, that is: the "server" process (or, the process with the "server" name) of the "basic-sample-jetty" distribution version "1.0", under the "dev" profile.

The same can be said of the kill command:

kill -d basic-sample-jetty -v 1.0 -n server -p dev

And similarly for the undeploy command:

undeploy -d basic-sample-jetty -v 1.0

The above commands are convenient, but can prove counter-productive when having to perform operations on multiple distributions or processes, which is often required in the context of deployment. The next section explores the solution to this problem.

Wildcards

Most command specifying options for filtering results also support wildcard matching. A concrete example will demonstrate this:

exec -d basic* -v * -n * -p dev

The above would target processes with any name, of distributions whose name starts with "basic", of any version, under profile "dev" (note that the profile option does not support wildcards).

Wildcard matching greatly improves productivity: imagine that a bunch of processes corresponding to a given distribution version are currently running, and that the deployment of a new version must be performed. You can use wilcards to optimize your manipulations. The following illustrates a sequence of commands corresponding to this scenario:

kill -d * -v * -n * -w
undeploy -d * -v *
deploy target/corus_sample_jetty*.zip

Consult the CLI's online help for more details about how each command supports wildcards.

Command Clustering

Although Corus clustering is not the subject of this tutorial, it is still relevant to mention it in the context of commands. Indeed, it is possible to execute commands not only "on" the Corus instance to which the CLI is currently connected, but on all instances in the cluster (or domain).

To "cluster" a command, one only needs specifiying the -cluster option at the end of the command-line, such as in:

exec -d corus* -v * -n * -p dev -cluster

This will start the process corresponding to the specified options on all Corus instances in the domain (provided they have the corresponding distribution).

Conclusion

In this tutorial, you've had a more in-depth look at the command-line interface. We suggest you explore the CLI's help. Have look at each command, especially the examples.