bwu_docker 0.3.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 5

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.

Use this package as a library

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:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages 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';
  
Version Uploaded Documentation Archive
0.3.0 Dec 1, 2015 Go to the documentation of bwu_docker 0.3.0 Download bwu_docker 0.3.0 archive
0.2.1 Jul 16, 2015 Go to the documentation of bwu_docker 0.2.1 Download bwu_docker 0.2.1 archive
0.2.0 May 8, 2015 Go to the documentation of bwu_docker 0.2.0 Download bwu_docker 0.2.0 archive
0.1.0+4 May 5, 2015 Go to the documentation of bwu_docker 0.1.0+4 Download bwu_docker 0.1.0+4 archive
0.1.0+3 May 5, 2015 Go to the documentation of bwu_docker 0.1.0+3 Download bwu_docker 0.1.0+3 archive
0.1.0+1 May 5, 2015 Go to the documentation of bwu_docker 0.1.0+1 Download bwu_docker 0.1.0+1 archive
0.1.0 May 5, 2015 Go to the documentation of bwu_docker 0.1.0 Download bwu_docker 0.1.0 archive

Analysis

We analyzed this package on Jul 13, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
0 / 100
Health:
Code health derived from static analysis. [more]
17 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
0 / 100
Overall score:
Weighted score of the above. [more]
5
Learn more about scoring.

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:bwu_docker/bwu_docker.dart.

Suggestions

  • Package is too old.

    The package was released more than two years ago.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 26 errors 120 hints.

    Strong-mode analysis of lib/src/shared/data_structures.dart failed with the following error:

    line: 192 col: 18
    The argument type '(Map<dynamic, dynamic>) → Null' can't be assigned to the parameter type '(dynamic) → void'.

    Strong-mode analysis of lib/src/shared/json_util.dart failed with the following error:

    line: 142 col: 14
    The return type 'UnmodifiableListView<T>' isn't a 'T', as defined by anonymous closure.

    Similar analysis of the following files failed:

    • lib/src/shared/version.dart (error)
    • lib/src/v1x15_and_up/data_structures.dart (error)
    • lib/src/v1x15_and_up/remote_api.dart (error)
    • lib/src/v1x15_and_up/tasks.dart (error)
    • lib/bwu_docker.dart (hint)
    • lib/src/shared/remote_api.dart (hint)
  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    None of the files in your example/ directory matches a known example patterns. Common file name patterns include: main.dart, example.dart or you could also use bwu_docker.dart.

  • Use analysis_options.yaml.

    Rename old .analysis_options file to analysis_options.yaml.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.9.0 <2.0.0
collection ^1.1.0 1.14.10
crypto ^0.9.0 0.9.2+1 2.0.6
http ^0.11.2 0.11.3+17
quiver_hashcode ^1.0.0-dev.1 1.0.0
stack_trace ^1.2.1 1.9.2
Transitive dependencies
async 2.0.7
charcode 1.1.2
convert 1.1.1 2.0.1
http_parser 3.1.2
path 1.6.1
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
Dev dependencies
bwu_grinder_tasks ^0.1.0
grinder >=0.7.0 <0.9.0
test ^0.12.3+1