Running Containers from the CLI¶
In the quickstart we used the command line to launch containers, map ports and start an interactive instance. Let’s have a closer look at what ‘tfnz’ is capable of.
usage: tfnz [-h] [--location x.20ft.nz] [--local x.local] [-v] [-q] [-ti] [-e [VAR=value | VAR]] [-f src:dest] [-m [uuid:mountpoint | tag:mountpoint]] [-p 8080:80] [-w subdomain.my.com[:www.my.com[:certname]]] [--ssh 2222] [-s] [-z] [--systemd firstname.lastname@example.org] [--identity ~/.ssh/some_id.pem] source [command] ... positional arguments: source if '.' runs the most recently added docker image; else this is the tag or hex id of an image to run. command run this command/entrypoint instead args arguments to pass to a script or subprocess optional arguments: -h, --help show this help message and exit connection options: --location x.20ft.nz use a non-default location --local x.local a non-dns ip for the location launch options: -v, --verbose verbose logging -q, --quiet no logging -ti, --interactive interactive, connect stdin and stdout -e [VAR=value | VAR], --env [VAR=value | VAR] set an environment variable, possibly from current -f src:dest, --file src:dest write a pre-boot file -m [uuid:mountpoint | tag:mountpoint], --mount [uuid:mountpoint | tag:mountpoint] mount a volume -p 8080:80, --publish 8080:80 add a local->remote tcp proxy -w subdomain.my.com[:www.my.com[:certname]], --web subdomain.my.com[:www.my.com[:certname]] publish on web endpoint development options: --ssh 2222 create an ssh/sftp wrapped shell on given port -s shorthand for --ssh 2222 -z, --sleep launch the container asleep (instead of entrypoint) server options: --systemd email@example.com create a systemd service --identity ~/.ssh/some_id.pem specify an identity file to use with --systemd
A Subset Of These Options Are Compatible With ‘docker run’
- -e and –env are the same between both platforms
- -m and –mount, use the syntax from ‘-v’ but refer to 20ft volumes and not local directories
- -p and –publish, still create container to local proxies, but only use the two part hostport:containerport syntax
- -ti, works the same but there is no -t or -i on its own
- trailing (optional) command and args are the same.
“location” can be passed to indicate that a location other than the default should be used (obviously you will need an account for this location). And “local” is to connect to a location by manually stating it’s IP. This is most commonly used for better performance when the server is on the local lan.
“verbose” and “quiet” work in the familiar way. Regardless of the verbosity settings, errors will still be printed on the stderr stream (and the return code will be 1).
“web” publishes to a web endpoint on the load balancer - see domains in the CLI administration section for guidance on how to use these.
“ssh” creates an ssh server onto the container - see ‘development’ later.
“systemd” creates and starts a systemd unit on a server or vps to which the user has ssh access; and “identity” specifies the pem file to use to connect.
The env and mount options can be used multiple times.
It is more performant to publish to a web endpoint than it is to create a proxy
Note that tfnz (mostly) assumes you have a local docker instance running. The times when you don’t need one are covered in the images section in the administration chapter.
You can only ever mount from the root of a volume. You cannot, for example, have a volume with subdirectories “mnt1” and “mnt2” and specify which subdirectory you want to mount within the container’s filesystem.
tfnz -w docs.sydney.20ft.nz tfnz/docs
Publishes the image for this documentation onto an endpoint: docs.sydney.20ft.nz
tfnz -ti alpine
Runs an alpine linux container interactively.
tfnz --sleep -s tfnz/docs
Spawns a container from the documentation image but doesn’t start it. It does, however, connect an ssh server from which we can mount the file system (sftp).
tfnz -e EXAM=ple -p 8000:80 tfnz/env_test
Spawns an environment testing container with ‘EXAM=ple’ set it its environment; and puts a tcp proxy between localhost:8000 and the webserver running on the container. curl http://localhost:8000 returns the environment inside the container.
tfnz -m example:/mnt -ti alpine
Runs an alpine linux container interactively with the persistent volume tagged ‘example’ mounted on /mnt.