github.com/docker/libcompose@v0.4.1-0.20210616120443-2a046c0bdbf2/README.md (about)

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