# README

dexec

dexec is a small Go library allowing you to run processes inside Docker containers as if you are running them locally using os/exec package. Read documentation at godoc.org or see examples.

Using dexec, you can do stream processing, off-load computationally expensive parts of your program to a remote fleet of Docker engines. Its interface is strikingly similar to os/exec.

Examples

Check out the following examples:

A Short Example

It takes only a 4-line code change to convert a piece of code using os/exec to use dexec to start running your stuff inside containers.

Here is a minimal Go program that runs echo in a container:

package main

import (
	"log"

	"github.com/ahmetalpbalkan/dexec"
	"github.com/fsouza/go-dockerclient"
)

func main(){
	cl, _ := docker.NewClient("unix:///var/run/docker.sock")
	d := dexec.Docker{cl}

	m, _ := dexec.ByCreatingContainer(docker.CreateContainerOptions{
	Config: &docker.Config{Image: "busybox"}})

	cmd := d.Command(m, "echo", `I am running inside a container!`)
	b, err := cmd.Output()
	if err != nil { log.Fatal(err) }
	log.Printf("%s", b)
}

Output: I am running inside a container!

Use Cases

This library is intended for providing an execution model that looks and feels like os/exec package.

You might want to use this library when:

You want to execute a process, but run it in a container with extra security and finer control over resource usage with Docker –and change your code minimally.
You want to execute a piece of work on a remote machine (or even better, a pool of machines or a cluster) through Docker. Especially useful to distribute computationally expensive workloads.

For such cases, this library abstracts out the details of executing the process in a container and gives you a cleaner interface you are already familiar with.

Check out more examples →