github.com/camronlevanger/libcompose@v0.4.1-0.20180423130544-6bb86d53fa21/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)) [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/docker/libcompose/docker" 31 "github.com/docker/libcompose/docker/ctx" 32 "github.com/docker/libcompose/project" 33 "github.com/docker/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/docker/libcompose/cli/main 75 --> darwin/amd64: github.com/docker/libcompose/cli/main 76 --> linux/386: github.com/docker/libcompose/cli/main 77 --> linux/amd64: github.com/docker/libcompose/cli/main 78 --> linux/arm: github.com/docker/libcompose/cli/main 79 --> windows/386: github.com/docker/libcompose/cli/main 80 --> windows/amd64: github.com/docker/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/docker/libcompose/docker 0.019s coverage: 4.6% of statements 134 + go test -cover -coverprofile=cover.out ./project 135 ok github.com/docker/libcompose/project 0.010s coverage: 8.4% of statements 136 + go test -cover -coverprofile=cover.out ./version 137 ok github.com/docker/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/docker/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.