github.com/xiaobinqt/libcompose@v1.1.0/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/xiaobinqt/libcompose?status.png)](https://godoc.org/github.com/xiaobinqt/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/xiaobinqt/libcompose/docker" 48 "github.com/xiaobinqt/libcompose/docker/ctx" 49 "github.com/xiaobinqt/libcompose/project" 50 "github.com/xiaobinqt/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/xiaobinqt/libcompose/cli/main 92 --> darwin/amd64: github.com/xiaobinqt/libcompose/cli/main 93 --> linux/386: github.com/xiaobinqt/libcompose/cli/main 94 --> linux/amd64: github.com/xiaobinqt/libcompose/cli/main 95 --> linux/arm: github.com/xiaobinqt/libcompose/cli/main 96 --> windows/386: github.com/xiaobinqt/libcompose/cli/main 97 --> windows/amd64: github.com/xiaobinqt/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/xiaobinqt/libcompose/docker 0.019s coverage: 4.6% of statements 151 + go test -cover -coverprofile=cover.out ./project 152 ok github.com/xiaobinqt/libcompose/project 0.010s coverage: 8.4% of statements 153 + go test -cover -coverprofile=cover.out ./version 154 ok github.com/xiaobinqt/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/xiaobinqt/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.