bwu_docker 0.3.0

Dart client for the Docker remote API

Star this Repo Pub Package Build Status Coverage Status

See Docker Remote API v1.21 for more details.

This package provides a typed interface to the Docker REST API and deserializes JSON response to Dart classes.

The intention is to make it easy to automate Docker related tasks from Grinder or other scripts. This package also makes it easy to build a dashboard for the Docker service.

Usage

See example below or the unit tests.

Ensure you have Docker listening on a TCP port (for more details see Bind Docker to another host/port or a Unix socket), because Dart currently can't communicate using Unix sockets (see Dart Issue 21403 - Support Unix Sockets in dart:io for details).

Supported commands

Containers

  • attach (Attach to a container)
  • changes (Changes to a containers file system)
  • container (Inspect a container)
  • containers (List containers)
  • copy (Copy files or folders from a container)
  • create (Create a container)
  • export (Export a container)
  • kill (Kill a container)
  • logs (Get container logs)
  • pause (Pause a container)
  • top (List processes running inside a container)
  • rename (Rename a container)
  • remove (Remove a container)
  • resize (Resize a container TTY)
  • restart (Restart a container)
  • start (Start a container)
  • stats (Get container stats based on resource usage)
  • stop (Stop a container)
  • unpause (Unpause a container)
  • wait (Wait a container)

Images

  • build (missing test) (Build image from a Dockerfile)
  • create (Create an image)
  • image (Inspect an image)
  • images (List images)
  • history (Get the history of an image)
  • push (missing test) (Push an image into a repository)
  • tag (Tag an image into a repository)
  • remove (Remove an image)
  • search (Search images)

Misc

  • auth (Check auth configuration)
  • commit (Create a new image from a containers changes)
  • events (Monitor Dockers events)
  • exec create (Set up an exec instance)
  • exec inspect (Inspect an exec command)
  • exec resize (missing test) (Resize the tty session)
  • exec start (Start an exec instance)
  • get (Get a tarball containing all images in a repository)
  • get all (missing test) (Get a tarball containing all images)
  • info (Display system-wide information)
  • load (missing test) (Load a tarball with a set of images and tags into Docker)
  • ping (Ping the docker server)
  • version (Show the Docker version information)

Feedback

I'm not a Docker specialist. If something isn't working as expected or you are missing a feature just create a bug report in the GitHub repo or even better, create a pull request.

TODO

  • container attachWs (Attach to a container using websocket)
  • image build (missing test) (Build image from a Dockerfile)
  • image push (missing test) (Push an image into a repository)
  • misc get all (missing test) (Get a tarball containing all images)
  • misc load (missing test) (Load a tarball with a set of images and tags into Docker)
  • exec resize (missing test) (Resize the tty session)

Example

Run docker pull busybox before runing the example to ensure the used image is available.

library bwu_docker.example.images;

import 'dart:io' as io;
import 'package:http/http.dart' as http;
import 'package:bwu_docker/bwu_docker.dart';

main() async {
  // initialize the connection to the Docker service
  final conn = new DockerConnection(
      Uri.parse(io.Platform.environment[dockerHostFromEnvironment]),
      new http.Client());
  await conn.init();

  // create a container from an image
  CreateResponse created = await conn.createContainer(
      new CreateContainerRequest()
    ..image = 'busybox'
    ..hostConfig.logConfig = {'Type': 'json-file'});

  // start the container
  await conn.start(created.container);

  // load the list of containers
  Iterable<Container> containers = await conn.containers();

  // investigate response
  var found = containers.firstWhere((c) => c.id == created.container.id);
  print('found: ${found.id}, name: ${found.names.join(', ')}\n');

  print('all:');
  containers.forEach((Container c) {
    print(
        'Container ID: ${c.id}, names: ${c.names.join(', ')}, status: ${c.status}');
  });

  // clean up
  await conn.stop(created.container);
  await conn.removeContainer(created.container);
}

For more examples check out the unit tests.

Also check out the BWU Docker wiki pages.

UNRELEASED

  • Some code restructuring because at some point it seemed necessary to split code int pre 1.20 and 1.20 or higher but actually wasn't.
  • Doesn't throw on unexpected JSON items anymore. This can be enabled by setting bool doCheckSurplusItems = true;
  • Partial support for Docker API v 1.20 and v.121 # TODO (zoechi) implement all new features
  • support in DockerConnection to use a specific remote API version
  • improve Docker container creation for running tests
  • apply new dartformat
  • update config for linter (Grinder task)
  • Started implementation of a run task
    • add publish parameter
    • add rm parameter
    • add link parameter
  • Breaking change:
    • Changed the PortBindings structure and implementation (fromJson/toJson)

0.2.1

  • Support for Docker API v 1.19
  • DockerConnection now takes an Uri instead of parts
  • Test and grinder read DOCKER_HOST_REMOTE environment variable to find the Docker service
  • A http.client needs to be passed to DockerConnection to allow to use it also in the browser
  • change toJson() methods so that only fields != null are added to the JSON output.

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  bwu_docker: "^0.3.0"

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support 'pub get'. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:bwu_docker/bwu_docker.dart';

Platforms

About

Typed Dart client for the Docker JSON remote API. Makes it easy to automate Docker tasks or build a Docker-dashboard.

Author

Email guenter@gzoechbauer.com Guenter Zoechbauer

Homepage

github.com/bwu-dart/bwu_docker

Documentation

www.dartdocs.org/documentation/bwu_docker/0.3.0/

Source code (hyperlinked)

www.crossdart.info/p/bwu_docker/0.3.0/

Uploader

gzoechi@gmail.com

Published

Dec 1, 2015

Share