# Docker - Perl 6 Docker API A simple wrapper around the [Docker REST API](https://docs.docker.com/engine/api/latest). Much of the API is not fully documented here -- it just follows the API. It is recommended that you be familiar with Docker in general and the API specifically before using this module to automate your Docker tasks. ## Basic Usage use Docker::API; my $d = Docker::API.new; # Defaults to /var/run/docker.sock $d.version; # Other stuff in version too $d.info; # Other stuff in info too $d.images; # List Images $d.containers; # List Containers $d.image-create(fromImage => 'alpine', tag => 'latest'); # image pull $d.container-create(name => 'foo', Image => 'alpine', Cmd => ( '/bin/echo', 'hello world!') ); $d.container-start(id => 'foo'); print $d.container-logs(id => 'foo'); $d.container-stop(id => 'foo'); $d.container-remove(id => 'foo'); ## Convenience class There is a `Docker::Container` class that remembers the container `id` for you. use Docker::Container; my $container = Docker::Container.new(Image => 'alpine', Cmd => ( '/bin/echo', 'hello world!')); $container.start; print $container.logs; $container.stop; $container.remove; ## Connection By default, Docker::API.new() will just use a unix socket on `/var/run/docker.sock` If you use a different socket name, you can pass in `:unix-socket-path`: my $docker = Docker::API.new(unix-socket-path => '/my/special/socket') If you have it running on a TCP port (hopefully you know what you are doing and do it securely), you can pass in a host/port like this: my $docker = Docker::API.new(host => 'somehost', port => 12345); If you know what you are doing, you can pass in other options for `LibCurl` and they just get passed through. One `LibCurl` option that is useful for debugging is `:verbose` which will dump out the HTTP headers. ## filters Many of the command have a `:%filters` option. You can construct your own hash of filter argument and just pass that in. If you pass in other arguments, they will get stuck into filters. For example: $docker.volumes(filters => { label => { foo => True } } ); and $docker.volumes(label => 'foo'); do the same thing. ## Streams Some commands such as `attach`, `stats`, `logs`, `events`, `exec`, etc. have options for streaming ongoing output. They return a `Docker::Stream` object. It is kind of, but not really like `Proc::Async`. It stringifies to just slurp in all the output and return it as a string, so you can do things like this: print $docker.logs(id => 'foo'); If you do that with something that keeps on streaming, it will keep on slurping forever and appear to hang. You can access `.stdout` and `.stderr` streams which are by default merged (and if you have a container with a `tty`, they are also merged so even if you ask for stderr, all output will be on stdout anyway). They are returned as supplies that must be tapped to use. You have to call `.start` to start the process. It returns a `Promise` that will be kept when the process completes. ``` my $stream = $docker.logs(id => $foo, :follow); $stream.stdout.tap({ .print }); await self.start; ``` You can also use react/whenever: ``` my $stream = $docker.logs(id => $foo, :follow); react { whenever $stream.stdout.lines { .put } whenever $stream.start { done } } ``` By default everything goes to stdout, but you can also separate out stderr and do something different: ``` my $stream = $docker.logs(id => $foo, :!merge, :stdout, :stderr, :follow); react { whenever $stream.stdout.lines { .put } whenever $stream.stderr(:bin) { # Binary Blobs instead of Strs .decode.put } whenever $stream.start { done } } ``` You can send input to the container (if you use the right options to attach/open stdin): ``` $docker.container-create(name => 'foo', Image => 'busybox', :AttachStdin, :OpenStdin, :AttachStdout), $docker.container-start(id => foo); my $stream = $docker.container-attach(id => foo); my $stdout = ''; $stream.stdout.tap({ $stdout ~= $_ }); # Capture stdout in a string my $p = $stream.start; # start the stream up $stream.print("echo hello world\nexit\n"); # Send two lines to stdin await($p); # Wait for the stream to close print $stdout; # Dump the string or do something else with it. ``` (Of course for something this simple, you are probably better off with `exec`, but you can really drive interactive stuff with this if you know what you are doing.) ## Authentication Using `image-create` to pull an image from a private repository or using `image-push` will require authentication to the image registry. You will need an authenication token, which is an insecure way of encoding authentication credentials. (Protect the token from disclosure like a password.) You can use the `token` method to create a token: my $auth-token = Docker::API.token( username => 'me', password => '********', serveraddress => 'https://index.docker.io/v1/'); You can also just create one manually from the command line: echo -n '{"username":"me","password":"*******","serveraddress":"quay.io"}' | base64 -w0 Pass that in to the `:auth-token` parameter to `Docker.new`: my $docker = Docker::API.new(:$auth-token); You can also set it later if you need multiple tokens (or just make multiple `Docker::API` objects.) $docker.auth-token = '...'; It will also use a token from environment variable `DOCKER_API_AUTH_TOKEN` if that is set. That is much preferred to embedding the password in a script. ## Methods ### auth(...) $docker.auth(username => 'me', password => '********', email => 'me@example.com', serveraddress => 'https://index.docker.io/v1/'); Validate credentials for a registry and, if available, get an identity token for accessing the registry without password. ### version() Returns the version of Docker that is running and various information about the system that Docker is running on. ### info() Get system information. ### df() Get data usage information. ### containers(Bool :$all, Int :$limit, Bool :$size, :%filters, |filters) Returns a list of containers. ### container-inspect(Str:D :$id!, Bool :$size) Return low-level information about a container. ### container-top(Str:D :$id!, Str :$ps_args) List processes running inside a container. On Unix systems, this is done by running the ps command. This endpoint is not supported on Windows. ### container-diff(Str:D :$id!) Get changes on a container’s filesystem (This is called 'changes' in the API, but 'diff' in the docker command line app.) Returns which files in a container's filesystem have been added, deleted, or modified. The Kind of modification can be one of: 0: Modified 1: Added 2: Deleted ### container-export(Str:D :$id!, Str :$download) Export the contents of a container as a tarball. Specify a filename in `:download` to save to disk, otherwise returns tar file as a `Buf`. ### container-stats(Str:D :$id, Bool :$stream = False) Get container stats based on resource usage This endpoint returns a live stream of a container’s resource usage statistics. Differently from the docker API, `:stream` is NOT the default. If you want a stream, pass in `:stream`, otherwise you just get a snapshot. Process a stream the normal way, through `stdout`: my $stream = $docker.container-stats(:$id, :stream); $stream.stdout.tap({ .say }); $stream.start; ### container-logs(Str:D :$id!, Bool :$merge = True, Bool :$stdout, Bool :$stderr, Int :$since, Int :$until, Bool :$timestamps, Str :$tail) Get stdout and stderr logs from a container. Note: This endpoint works only for containers with the json-file or journald logging driver. Note, this sets `:merge`, an additional option specific to this module, by default to true. `:merge` will automatically select *both* `:stdout` and `:stderr` and merge them into a single stream. If you don't want that, pass in `:!merge` and `:stdout` and/or `:stderr`. If you pass in `:follow` it will leave the connection open and stream output to you. ### container-start(Str:D :$id!, Str :$detachKeys) Start a container `:detachKeys` - Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl- where is one of: a-z, @, ^, [, , or _. ### container-stop(Str:D :$id!, Int :$t) Stop a container `:t` = Number of seconds to wait before killing the container ### container-restart(Str:D :$id!, Int :$t) Restart a container `:t` = Number of seconds to wait before restarting the container ### container-kill(Str:D :$id!, Cool :$signal) Kill a container Send a POSIX signal to a container, defaulting to killing to the container. :signal can be a POSIX signal integer or string (e.g. `SIGINT`) default `SIGKILL` ### container-rename(Str:D :$id!, Str:D :$name!) Rename a container ### container-pause(Str:D :$id!) Pause a container Use the cgroups freezer to suspend all processes in a container. Traditionally, when suspending a process the SIGSTOP signal is used, which is observable by the process being suspended. With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. ### container-unpause(Str:D :$id!) Unpause a container Resume a container which has been paused. ### container-attach(Str:D :$id!, Bool :$tty, Str :$detachKeys, Bool :$logs, Bool :$stream = True, Bool :$stdin = True, Bool :$stdout = True, Bool :$stderr = True, Bool :$merge = True, Str :$enc = 'utf8', Bool :$translate-nl = True, Int :$timeout = 3600000) Attach to a container Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached. Either the stream or logs parameter must be true for this endpoint to do anything. ### container-wait(Str:D :$id!, Str :$condition) Wait for a container Block until a container stops, then returns the exit code. `:condition` = `not-running` (default), `next-exit`, `removed` ### container-remove(Str:D :$id!, Bool :$v, Bool :$force, Bool :$link) Remove a container `:v` - Remove the volumes associated with the container. `:force` - If the container is running, kill it before removing it. `:link` - Remove the specified link associated with the container. ### container-archive-info(Str :$id!, Str :$path!) Get information about files in a container ### container-archive(Str :$id!, Str:D :$path!, Str :$download) Get a tar archive of a resource in the filesystem of container id. Specify a filename in `:download` to save to disk, otherwise returns tar file as a `Buf`. You can extract files from the tar file (even in a memory Buf) using the ecosystem module `Libarchive`. ### container-copy(Str:D :$id!, Str:D :$path!, Bool :$noOverwriteDirNonDir, Str :$upload, Buf :$send) Extract an archive of files or folders to a directory in a container Upload a tar archive to be extracted to a path in the filesystem of container id. You specify either the filename of a tar file with `:upload`, or use `:send` to upload directly from a memory `Buf`. ### containers-prune(:%filters, |filters) Delete stopped containers ### container-create(Str :$name, *%fields) my $container = $docker.container-create( Image => 'alpine', Cmd => ( 'echo', 'hello world' )); put $container; ### container-update(Str:D :$id!, *%fields) Update a container Change various configuration options of a container without having to recreate it. ### images(:%filters, Bool :$all, Bool :$digests) Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image. my $list = $docker.images(reference => { 'alpine' }); ..say for @$list; ### image-create(Str :$fromImage, Str :$fromStr, Str :$repo, Str :$tag, Str :$platform) $docker.image-create(fromImage => 'alpine', tag => 'latest'); ### image-build(Str :$dockerfile, :@t, Str :$extrahosts, Str :$remote, Bool :$q, Bool :$nocache, :@cachefrom, Str :$pull, Bool :$rm, Bool :$forcerm, Int :$memory, Int :$memswap, Int :$cpushares, Str :$cpusetcpus, Int :$cpuperiod, Int :$cpuquota, :%buildargs, Int :$shmsize, Bool :$squash, :%labels, Str :$networkmode, Str :$platform, Str :$target) $docker.image-build(:q, :rm, t => ['docker-perl-testing:test-version'], remote => 'https://github.com/CurtTilmes/docker-test.git') `:q` = quiet `:rm` = Remove intermediate containers after a successful build `:remote` = A URL, can be for a git repository, or a single file that is a Dockerfile, or a single file that is a tarball with a Dockerfile in it. If you rename the dockerfile, pass in `:dockerfile` to tell it which file is the Dockerfile. You can also bundle the `Dockerfile` and other optional files into a tar file: use Libarchive::Simple; with archive-write(my $tarfile = Buf.new, format => 'paxr') { .write('Dockerfile', q:to/DOCKERFILE/); FROM alpine:latest LABEL maintainer="Curt Tilmes " ENTRYPOINT ["/bin/ash"] DOCKERFILE .close; } $docker.image-build($tarfile, t => ['myimage:myversion']); ### image-inspect(Str:D :$name!) Return low-level information about an image. ### image-history(Str:D :$name!) Return parent layers of an image. ### image-tag(Str:D :$name!, Str :$repo, Str :$tag) Tag an image so that it becomes part of a repository. ### image-push(Str:D :$name!, Str :$tag) Push an image to a registry. If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, registry.example.com/myimage:latest. The push is cancelled if the HTTP connection is closed. ### image-remove(Str:D :$name!, Bool :$force, Bool :$noprune) Remove an image, along with any untagged parent images that were referenced by that image. Images can't be removed if they have descendant images, are being used by a running container or are being used by a build. ### images-search(Str:D :$term, Int :$limit, :%filters, Bool :$is-official, Bool :$is-automated, Int :$stars) my $list = $docker.images-search(term => 'alpine', limit => 10, :is-official, :!is-automated, :5000stars); for @$list { say .; say .; } ### images-prune(:%filters, :$dangling :$until :$label) ### image-get(Str:D :$name!, Str :$download) Returns Blob of a tar file You can pass in a filename in `:download` and it will dump the tar file into that file. ### images-get(:@names) Returns Blob of a tar file You can pass in a filename in `:download` and it will dump the tar file into that file. ### images-load(Bool :$quiet, Str :$upload) ### images-load(Blob $blob, Bool :$quiet) Upload a tar file with images. You can specify a filename to upload with `:upload`: $docker.images-load(upload => 'foo.tar'); or just pass in a `Blob`: $docker.images-load($tarblob); ### volumes(:%filters, :$name, :$label) $docker.volumes(filters => { label => { foo => True } } ); $docker.volumes(label => 'foo'); # has label foo $docker.volumes(label => 'foo=bar'); # has label foo = 'bar' $docker.volumes(label => ); # has both labels foo and bar $docker.volumes(name => 'foo'); # volume with name foo $docker.volumes(name => ); # volume with name foo or bar ### volume-create(...) Everything is optional, it will make a random volume. $docker.volume-create(Name => 'foo', Labels => { foo => 'bar' }); ### volume-inspect(:$name) ### volume-remove(:$name, :force) `:name` required `:force` boolean ### volume-prune(:%filters) ### networks(:%filters, ...) ### network-inspect(Str:D :$id!, Bool :$verbose, Str :$scope) ### network-create(...) $docker.network-create(Name => 'foo'); lots of other options ### network-connect(Str:D :$id!, ...) `:Container` id or name `:EndpointConfig` lots of options ### network-disconnect(Str:D :$id!, ...) `:Container` `:Force` ### networks-prune(:%filters, ...) ### exec-create(Str:D :$id!, ...) `:id` of container ### exec-start(Str:D :$id!, ...) ### exec-resize(Str:D :$id!, Int :$h, Int :$w) Resize the TTY for a container. You must restart the container for the resize to take effect. ### exec-inspect(Str:D :$id!) `:id` of exec ### exec(Str:D :$id!, ...) call `exec-create(:$id, ...)`, then `exec-start()` ### events(Str :$since, Str :$until, :$timeout, :%filters) Stream real-time events from the server. Various objects within Docker report events when something happens to them. Returns a Supply of Events: my $events = $docker.events(); $events.tap({ .say } The events come as hashes, so you can break out the fields Action, Actor, id, time, etc. and react to specific actions: react { whenever $events -> % (:$Action, :$id, :$time, *%) { ... } } ### plugins(%filters, ...) ### distribution(Str:D :$name!) ## INSTALL Uses [LibCurl](https://github.com/CurtTilmes/LibCurl) to communicate with Docker, so that will need to be installed. Since it depends on the [libcurl](https://curl.haxx.se/download.html) library, you must also install that first. ## LICENSE Copyright © 2019 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. No copyright is claimed in the United States under Title 17, U.S.Code. All Other Rights Reserved.