github.com/ajspeck/libcompose@v0.5.4/README.md (about)

     1  # libcompose
     2  
     3  [![GoDoc](https://godoc.org/github.com/ajspeck/libcompose?status.png)](https://godoc.org/github.com/ajspeck/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 not really maintained anymore — the reason are diverse but mainly lack of time from the maintainers**
     9  
    10  The current state is the following :
    11  - The `libcompose` CLI should considered abandonned. The `v2` parsing is incomplete and `v3` parsing is missing.
    12  - The official compose Go parser implementation is on [`docker/cli`](https://github.com/docker/cli/tree/master/cli/compose) but only support `v3` version of the compose format.
    13  
    14  What is the work that is needed:
    15  - Remove the cli code (thus removing dependencies to `docker/cli` )
    16  - Clearer separation of packages : `parsing`, `conversion` (to docker api or swarm api), `execution` (`Up`, `Down`, … behaviors)
    17  - Add support for all compose format version (v1, v2.x, v3.x)
    18  - Switch to either `golang/dep` or `go mod` for dependencies (removing the `vendor` folder)
    19  - *(bonus)* extract the [`docker/cli`](https://github.com/docker/cli/tree/master/cli/compose) code here and vendor this library into `docker/cli`.
    20  
    21  If you are interested to work on `libcompose`, feel free to ping me (over twitter @vdemeest), I'll definitely do code reviews and help as much as I can 😉.
    22  
    23  **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.**
    24  
    25  Here is a list of known project that uses `libcompose`:
    26  
    27  - [rancher-compose](https://github.com/rancher/rancher-compose) and [rancher os](https://github.com/rancher/os) (by [Rancher](https://github.com/rancher))
    28  - [openshift](https://github.com/openshift/origin) (by [Red Hat](https://github.com/openshift))
    29  - [henge](https://github.com/redhat-developer/henge) (by [Red Hat](https://github.com/redhat-developer)) [Deprecated in favour of kompose]
    30  - [kompose](https://github.com/skippbox/kompose) (by [skippbox](https://github.com/skippbox))
    31  - [compose2kube](https://github.com/kelseyhightower/compose2kube) (by [kelseyhightower](https://github.com/kelseyhightower))
    32  - [amazon-ecs-cli](https://github.com/aws/amazon-ecs-cli) (by [Amazon AWS](https://github.com/aws))
    33  - [libkermit](https://github.com/libkermit/docker) (by [vdemeester](https://github.com/vdemeester))
    34  
    35  ## Usage
    36  
    37  ```go
    38  package main
    39  
    40  import (
    41  	"log"
    42  
    43  	"golang.org/x/net/context"
    44  
    45  	"github.com/ajspeck/libcompose/docker"
    46  	"github.com/ajspeck/libcompose/docker/ctx"
    47  	"github.com/ajspeck/libcompose/project"
    48  	"github.com/ajspeck/libcompose/project/options"
    49  )
    50  
    51  func main() {
    52  	project, err := docker.NewProject(&ctx.Context{
    53  		Context: project.Context{
    54  			ComposeFiles: []string{"docker-compose.yml"},
    55  			ProjectName:  "my-compose",
    56  		},
    57  	}, nil)
    58  
    59  	if err != nil {
    60  		log.Fatal(err)
    61  	}
    62  
    63  	err = project.Up(context.Background(), options.Up{})
    64  
    65  	if err != nil {
    66  		log.Fatal(err)
    67  	}
    68  }
    69  ```
    70  
    71  
    72  ## Building
    73  
    74  You need either [Docker](http://github.com/docker/docker) and `make`,
    75  or `go` in order to build libcompose.
    76  
    77  ### Building with `docker`
    78  
    79  You need Docker and ``make`` and then run the ``binary`` target. This
    80  will create binary for all platform in the `bundles` folder.
    81  
    82  ```bash
    83  $ make binary
    84  docker build -t "libcompose-dev:refactor-makefile" .
    85  # […]
    86  ---> Making bundle: binary (in .)
    87  Number of parallel builds: 4
    88  
    89  -->      darwin/386: github.com/ajspeck/libcompose/cli/main
    90  -->    darwin/amd64: github.com/ajspeck/libcompose/cli/main
    91  -->       linux/386: github.com/ajspeck/libcompose/cli/main
    92  -->     linux/amd64: github.com/ajspeck/libcompose/cli/main
    93  -->       linux/arm: github.com/ajspeck/libcompose/cli/main
    94  -->     windows/386: github.com/ajspeck/libcompose/cli/main
    95  -->   windows/amd64: github.com/ajspeck/libcompose/cli/main
    96  
    97  $ ls bundles
    98  libcompose-cli_darwin-386*    libcompose-cli_linux-amd64*      libcompose-cli_windows-amd64.exe*
    99  libcompose-cli_darwin-amd64*  libcompose-cli_linux-arm*
   100  libcompose-cli_linux-386*     libcompose-cli_windows-386.exe*
   101  ```
   102  
   103  
   104  ### Building with `go`
   105  
   106  - You need `go` v1.11 or greater
   107  - you need to set export `GO111MODULE=on` environment variable
   108  - If your working copy is not in your `GOPATH`, you need to set it
   109  accordingly.
   110  
   111  ```bash
   112  $ go generate
   113  # Generate some stuff
   114  $ go build -o libcompose ./cli/main
   115  ```
   116  
   117  
   118  ## Running
   119  
   120  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.
   121  
   122  Run one of these:
   123  
   124  ```
   125  libcompose-cli_darwin-386
   126  libcompose-cli_linux-amd64
   127  libcompose-cli_windows-amd64.exe
   128  libcompose-cli_darwin-amd64
   129  libcompose-cli_linux-arm
   130  libcompose-cli_linux-386
   131  libcompose-cli_windows-386.exe
   132  ```
   133  
   134  ## Tests (unit & integration)
   135  
   136  
   137  You can run unit tests using the `test-unit` target and the
   138  integration test using the `test-integration` target. If you don't use
   139  Docker and `make` to build `libcompose`, you can use `go test` and the
   140  following scripts : `hack/test-unit` and `hack/test-integration`.
   141  
   142  ```bash
   143  $ make test-unit
   144  docker build -t "libcompose-dev:refactor-makefile" .
   145  #[…]
   146  ---> Making bundle: test-unit (in .)
   147  + go test -cover -coverprofile=cover.out ./docker
   148  ok      github.com/ajspeck/libcompose/docker     0.019s  coverage: 4.6% of statements
   149  + go test -cover -coverprofile=cover.out ./project
   150  ok      github.com/ajspeck/libcompose/project    0.010s  coverage: 8.4% of statements
   151  + go test -cover -coverprofile=cover.out ./version
   152  ok      github.com/ajspeck/libcompose/version    0.002s  coverage: 0.0% of statements
   153  
   154  Test success
   155  ```
   156  
   157  
   158  ## Current status
   159  
   160  The project is still being kickstarted... But it does a lot.  Please try it out and help us find bugs.
   161  
   162  ## Contributing
   163  
   164  Want to hack on libcompose? [Docker's contributions guidelines](https://github.com/ajspeck/libcompose/blob/master/CONTRIBUTING.md) apply.
   165  
   166  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.