rust interface for maneuvering docker containers
Clone or download
Pull request Compare This branch is 81 commits behind softprops:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
src
.gitignore
.travis.yml
CHANGELOG.md
Cargo.toml
LICENSE
README.md
rustfmt.toml

README.md

shiplift

Build Status crates.io MIT licensed

a rust interface for maneuvering docker containers

install

Add the following to your Cargo.toml file

[dependencies]
shiplift = "0.3"

docs

Find them here.

usage

Some small example programs can be found in this repository's examples directory.

communicating with hosts

To use shiplift, you must first have a docker daemon readily accessible. Typically this daemon processs is resolvable via a url specified by an env var named DOCKER_HOST. If you are using osx, docker-machine typically will have already set up every thing you need to get started when you run docker-machine env {envid}.

extern crate shiplift;
let docker = shiplift::Docker::new();

If you wish to be more explicit you can provide a host in the form of a url.Url.

extern crate shiplift;
extern crate url;

use shiplift::Docker;
use url::Url;

let docker = Docker::host(Url::parse("http://yourhost").unwrap());

images

If you are interacting with docker containers, chances are you will also need to interact with docker image information. You can interact docker images with docker.images().

extern crate shiplift;

use shiplift::Docker;

let docker = Docker.new();
let images = docker.images();

list host-local images

for i in images.list(&Default::default()).unwrap() {
  println!("-> {:?}", i);
}

find remote images

for i in image.search("rust").unwrap() {
  println!("- {:?}", i);
}

creating new image by pulling an existing image

use shiplift::PullOptions;
let output = images.pull(
  &PullOptions::builder().image("redis:2.8.18").build()
).unwrap();
for o in output {
  println!("{:?}", o);
}

build an image from the contents of a directory containing a Dockerfile

the following is equivalent to docker build -t shiplift_test .

use shiplift::BuildOptions;

let output = images.build(
     &BuildOptions::builder(".").tag("shiplift_test").build()
).unwrap();
for o in output {
    println!("{:?}", o);
}

accessing image info

let img = images.get("imagename");
inspecting image info
println!("- {:?}", img.inspect().unwrap());
getting image history
for h in img.history().unwrap() {
  println!("- {:?}", h);
}
deleting image
println!("- {:?}", img.delete().unwrap());

containers

Containers are instances of images. To gain access to this interface use docker.containers()

extern crate shiplift;

use shiplift::Docker;

let docker = Docker.new();
let containers = docker.containers();

listing host local containers

for c in containers.list(&Default::default()).unwrap() {
  println!("- {:?}", c);
}

get a container reference

let container = containers.get("containerid");

inspect container details

println!("- {:?}", container.inspect());

access top info

println!("- {:?}", container.top().unwrap());

view container logs

(todoc)

view a list of container changes

for c in container.changes().unwrap() {
  println!("- {:?}", c);
}

stream container stats

for stats in container.stats().unwrap() {
  println!("- {:?}", stats);
}

stop, start, restart container

container.stop();
container.start();
container.restart();

misc

todoc

roadmap

There are plans on switching from rustc-serialize to serde for serialization in 0.4.0 this should not have major impact on current interfaces.

Doug Tangren (softprops) 2015-2016