github.com/click2cloud/libcompose@v0.4.1-0.20170816121048-7c20f79ac6b9/README.md (about)

     1  # libcompose
     2  
     3  [![GoDoc](https://godoc.org/github.com/Click2Cloud/libcompose?status.png)](https://godoc.org/github.com/Click2Cloud/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)) [Deprecated in favour of kompose]
    15  - [kompose](https://github.com/skippbox/kompose) (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/Click2Cloud/libcompose/docker"
    31  	"github.com/Click2Cloud/libcompose/docker/ctx"
    32  	"github.com/Click2Cloud/libcompose/project"
    33  	"github.com/Click2Cloud/libcompose/project/options"
    34  )
    35  
    36  func main() {
    37  	project, err := docker.NewProject(&ctx.Context{
    38  		Context: project.Context{
    39  			ComposeFiles: []string{"docker-compose.yml"},
    40  			ProjectName:  "my-compose",
    41  		},
    42  	}, nil)
    43  
    44  	if err != nil {
    45  		log.Fatal(err)
    46  	}
    47  
    48  	err = project.Up(context.Background(), options.Up{})
    49  
    50  	if err != nil {
    51  		log.Fatal(err)
    52  	}
    53  }
    54  ```
    55  
    56  
    57  ## Building
    58  
    59  You need either [Docker](http://github.com/docker/docker) and `make`,
    60  or `go` in order to build libcompose.
    61  
    62  ### Building with `docker`
    63  
    64  You need Docker and ``make`` and then run the ``binary`` target. This
    65  will create binary for all platform in the `bundles` folder.
    66  
    67  ```bash
    68  $ make binary
    69  docker build -t "libcompose-dev:refactor-makefile" .
    70  # […]
    71  ---> Making bundle: binary (in .)
    72  Number of parallel builds: 4
    73  
    74  -->      darwin/386: github.com/Click2Cloud/libcompose/cli/main
    75  -->    darwin/amd64: github.com/Click2Cloud/libcompose/cli/main
    76  -->       linux/386: github.com/Click2Cloud/libcompose/cli/main
    77  -->     linux/amd64: github.com/Click2Cloud/libcompose/cli/main
    78  -->       linux/arm: github.com/Click2Cloud/libcompose/cli/main
    79  -->     windows/386: github.com/Click2Cloud/libcompose/cli/main
    80  -->   windows/amd64: github.com/Click2Cloud/libcompose/cli/main
    81  
    82  $ ls bundles
    83  libcompose-cli_darwin-386*    libcompose-cli_linux-amd64*      libcompose-cli_windows-amd64.exe*
    84  libcompose-cli_darwin-amd64*  libcompose-cli_linux-arm*
    85  libcompose-cli_linux-386*     libcompose-cli_windows-386.exe*
    86  ```
    87  
    88  
    89  ### Building with `go`
    90  
    91  - You need `go` v1.5 or greater
    92  - If you are not using `go` v1.6, you need to set export `GO15VENDOREXPERIMENT=1` environment variable
    93  - If your working copy is not in your `GOPATH`, you need to set it
    94  accordingly.
    95  
    96  ```bash
    97  $ go generate
    98  # Generate some stuff
    99  $ go build -o libcompose ./cli/main
   100  ```
   101  
   102  
   103  ## Running
   104  
   105  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.
   106  
   107  Run one of these:
   108  
   109  ```
   110  libcompose-cli_darwin-386
   111  libcompose-cli_linux-amd64
   112  libcompose-cli_windows-amd64.exe
   113  libcompose-cli_darwin-amd64
   114  libcompose-cli_linux-arm
   115  libcompose-cli_linux-386
   116  libcompose-cli_windows-386.exe
   117  ```
   118  
   119  ## Tests (unit & integration)
   120  
   121  
   122  You can run unit tests using the `test-unit` target and the
   123  integration test using the `test-integration` target. If you don't use
   124  Docker and `make` to build `libcompose`, you can use `go test` and the
   125  following scripts : `hack/test-unit` and `hack/test-integration`.
   126  
   127  ```bash
   128  $ make test-unit
   129  docker build -t "libcompose-dev:refactor-makefile" .
   130  #[…]
   131  ---> Making bundle: test-unit (in .)
   132  + go test -cover -coverprofile=cover.out ./docker
   133  ok      github.com/Click2Cloud/libcompose/docker     0.019s  coverage: 4.6% of statements
   134  + go test -cover -coverprofile=cover.out ./project
   135  ok      github.com/Click2Cloud/libcompose/project    0.010s  coverage: 8.4% of statements
   136  + go test -cover -coverprofile=cover.out ./version
   137  ok      github.com/Click2Cloud/libcompose/version    0.002s  coverage: 0.0% of statements
   138  
   139  Test success
   140  ```
   141  
   142  
   143  ## Current status
   144  
   145  The project is still being kickstarted... But it does a lot.  Please try it out and help us find bugs.
   146  
   147  ## Contributing
   148  
   149  Want to hack on libcompose? [Docker's contributions guidelines](https://github.com/Click2Cloud/libcompose/blob/master/CONTRIBUTING.md) apply.
   150  
   151  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.