CaskTutorial.md

Cask Tutorial

A quick introduction to most of Cask's features and usage patterns.

Installation

See the README for installation instructions.

Quickstart

Let's start by downloading and importing an image. The default image is essentially a blank slate, including only the busybox binary and symlinks.

$ cask image.import default https://ianpreston.io/cask/images/default.tar.gz

The first argument to image.import is the name the image should have, the second argument is a filename or HTTP URL of an exported image file.

After importing, the image should show up in the images list:

$ cask image.ls
Image Name
default

Now that we have an image, we can create a container from it. Let's create a container named example:

$ cask create example default

The new container will now be visible in the container list:

$ cask ls
Container Name                   Status  PID     IP Address
example                          down            10.18.66.58

Let's start it up:

$ sudo cask start example
$ cask ls
Container Name                   Status  PID     IP Address
example                          up      6705    10.18.66.58

Now that the container is running, the run command can be used to execute arbitrary commands within the container. Let's use sh to open a shell inside the container

$ sudo cask run example sh
/ # 

Networking

Each container gets its own IP by default. Containers are bridged with eachother, but not with the host's physical network interfaces. So containers are free to communicate with other containers, but cannot talk on the host's network (i.e. out to the internet).

For example, if the container starts a listen server:

$ sudo cask run example sh
/ # nc -l -p 1234

The host can telnet in like so:

$ telnet 10.18.66.58 1234

Creating an Image

Files can be copied from the host into a container with the copy command. Let's create a "helloworld" file in the container.

$ echo "Hello, world!" > helloworld
$ cask copy example helloworld /helloworld

We can verify that the file was copied by cat'ing it within the container:

$ sudo cask run example "cat /helloworld"
Hello, world!

An image can be created from a container using the freeze command.

Let's create a new image, myimage, from the example container. This image will resemble the default image but with the new helloworld file.

$ cask freeze example myimage
$ cask image.ls
Image Name
default
myimage

This new image can be exported for distribution using the image.export command:

$ cask image.export myimage myimage.tar.gz

Entry Points

Containers have a property called an "entry point". When the container starts up, it runs the entry point command as PID 1. When the entry point exits, the container shuts down.

The entry point for a container can be changed with the set command:

$ cask set example entrypoint "/busybox-i686 sleep 10"

The entry point can also be set at create time:

$ cask create mycontainer myimage --entrypoint="/busybox-i686 sleep 10"

Stdout and stderr from PID 1 are redirected to a log file on the host's filesystem. You can view the logs with the tail command:

$ cask tail -f example

Teardown

A container can be shut down with the kill command:

$ sudo cask kill example

When a container is shutdown, all of its state is saved for the next time it is run. This includes filesystem state, network settings, logs, etc.

A container can be completely destroyed with the destroy command:

$ sudo cask destroy example