github.com/bdwilliams/libcompose@v0.3.1-0.20160826154243-d81a9bdacff0/README.md (about)

     1  # libcompose
     2  
     3  [![GoDoc](https://godoc.org/github.com/docker/libcompose?status.png)](https://godoc.org/github.com/docker/libcompose)
     4  [![Build Status](https://jenkins.dockerproject.org/job/docker/job/libcompose/branch/master/badge/icon)](https://jenkins.dockerproject.org/job/docker/job/libcompose/branch/master/)
     5  
     6  A Go library for Docker Compose. It does everything the command-line tool does, but from within Go -- read Compose files, start them, scale them, etc.
     7  
     8  **Note: This is experimental and not intended to replace the [Docker Compose](https://github.com/docker/compose) command-line tool. If you're looking to use Compose, head over to the [Compose installation instructions](http://docs.docker.com/compose/install/) to get started with it.**
     9  
    10  Here is a list of known project that uses `libcompose`:
    11  
    12  - [rancher-compose](https://github.com/rancher/rancher-compose) and [rancher os](https://github.com/rancher/os) (by [Rancher](https://github.com/rancher))
    13  - [openshift](https://github.com/openshift/origin) (by [Red Hat](https://github.com/openshift))
    14  - [henge](https://github.com/redhat-developer/henge) (by [Red Hat](https://github.com/redhat-developer))
    15  - [kompose](https://github.com/skippbox/kompose2) (by [skippbox](https://github.com/skippbox))
    16  - [compose2kube](https://github.com/kelseyhightower/compose2kube) (by [kelseyhightower](https://github.com/kelseyhightower))
    17  - [amazon-ecs-cli](https://github.com/aws/amazon-ecs-cli) (by [Amazon AWS](https://github.com/aws))
    18  - [libkermit](https://github.com/libkermit/docker) (by [vdemeester](https://github.com/vdemeester))
    19  
    20  ## Usage
    21  
    22  ```go
    23  package main
    24  
    25  import (
    26  	"log"
    27  
    28  	"golang.org/x/net/context"
    29  
    30  	"github.com/docker/libcompose/docker"
    31  	"github.com/docker/libcompose/project"
    32  	"github.com/docker/libcompose/project/options"
    33  )
    34  
    35  func main() {
    36  	project, err := docker.NewProject(&docker.Context{
    37  		Context: project.Context{
    38  			ComposeFiles: []string{"docker-compose.yml"},
    39  			ProjectName:  "my-compose",
    40  		},
    41  	}, nil)
    42  
    43  	if err != nil {
    44  		log.Fatal(err)
    45  	}
    46  
    47  	err = project.Up(context.Background(), options.Up{})
    48  
    49  	if err != nil {
    50  		log.Fatal(err)
    51  	}
    52  }
    53  ```
    54  
    55  
    56  ## Building
    57  
    58  You need either [Docker](http://github.com/docker/docker) and `make`,
    59  or `go` in order to build libcompose.
    60  
    61  ### Building with `docker`
    62  
    63  You need Docker and ``make`` and then run the ``binary`` target. This
    64  will create binary for all platform in the `bundles` folder. 
    65  
    66  ```bash
    67  $ make binary
    68  docker build -t "libcompose-dev:refactor-makefile" .
    69  # […]
    70  ---> Making bundle: binary (in .)
    71  Number of parallel builds: 4
    72  
    73  -->      darwin/386: github.com/docker/libcompose/cli/main
    74  -->    darwin/amd64: github.com/docker/libcompose/cli/main
    75  -->       linux/386: github.com/docker/libcompose/cli/main
    76  -->     linux/amd64: github.com/docker/libcompose/cli/main
    77  -->       linux/arm: github.com/docker/libcompose/cli/main
    78  -->     windows/386: github.com/docker/libcompose/cli/main
    79  -->   windows/amd64: github.com/docker/libcompose/cli/main
    80  
    81  $ ls bundles
    82  libcompose-cli_darwin-386*    libcompose-cli_linux-amd64*      libcompose-cli_windows-amd64.exe*
    83  libcompose-cli_darwin-amd64*  libcompose-cli_linux-arm*
    84  libcompose-cli_linux-386*     libcompose-cli_windows-386.exe*
    85  ```
    86  
    87  
    88  ### Building with `go`
    89  
    90  - You need `go` v1.5 or greater
    91  - If you are not using `go` v1.6, you need to set export `GO15VENDOREXPERIMENT=1` environment variable
    92  - If your working copy is not in your `GOPATH`, you need to set it
    93  accordingly.
    94  
    95  ```bash
    96  $ go generate
    97  # Generate some stuff
    98  $ go build -o libcompose ./cli/main
    99  ```
   100  
   101  
   102  ## Running
   103  
   104  A partial implementation of the libcompose-cli CLI is also implemented in Go. The primary purpose of this code is so one can easily test the behavior of libcompose.
   105  
   106  Run one of these:
   107  
   108  ```
   109  libcompose-cli_darwin-386
   110  libcompose-cli_linux-amd64
   111  libcompose-cli_windows-amd64.exe
   112  libcompose-cli_darwin-amd64
   113  libcompose-cli_linux-arm
   114  libcompose-cli_linux-386
   115  libcompose-cli_windows-386.exe
   116  ```
   117  
   118  ## Tests (unit & integration)
   119  
   120  
   121  You can run unit tests using the `test-unit` target and the
   122  integration test using the `test-integration` target. If you don't use
   123  Docker and `make` to build `libcompose`, you can use `go test` and the
   124  following scripts : `script/test-unit` and `script/test-integration`.
   125  
   126  ```bash
   127  $ make test-unit
   128  docker build -t "libcompose-dev:refactor-makefile" .
   129  #[…]
   130  ---> Making bundle: test-unit (in .)
   131  + go test -cover -coverprofile=cover.out ./docker
   132  ok      github.com/docker/libcompose/docker     0.019s  coverage: 4.6% of statements
   133  + go test -cover -coverprofile=cover.out ./project
   134  ok      github.com/docker/libcompose/project    0.010s  coverage: 8.4% of statements
   135  + go test -cover -coverprofile=cover.out ./version
   136  ok      github.com/docker/libcompose/version    0.002s  coverage: 0.0% of statements
   137  
   138  Test success
   139  ```
   140  
   141  
   142  ## Current status
   143  
   144  The project is still being kickstarted... But it does a lot.  Please try it out and help us find bugs.
   145  
   146  ## Contributing
   147  
   148  Want to hack on libcompose? [Docker's contributions guidelines](https://github.com/docker/libcompose/blob/master/CONTRIBUTING.md) apply.
   149  
   150  If you have comments, questions, or want to use your knowledge to help other, come join the conversation on IRC. You can reach us at #libcompose on Freenode.