github.com/beanworks/dcm@v0.0.0-20230726194615-49d2d0417e04/README.md (about) 1 # DCM := "Docker-Compose Manager" 2 3 [](https://travis-ci.org/beanworks/dcm) 4 [](https://coveralls.io/github/beanworks/dcm) 5 [](https://goreportcard.com/report/github.com/beanworks/dcm) 6 7 ```text 8 9 _____ _____ ______ _______ 10 ___|\ \ ___|\ \ | \/ \ 11 | |\ \ / /\ \ / /\ \ 12 | | | || | | | / /\ / /\ | 13 | | | || | |____| / /\ \_/ / / /| 14 | | | || | ____ | | \|_|/ / / | 15 | | | || | | || | | | | 16 |____|/____/||\ ___\/ /||\____\ |____| / 17 | / | || | /____/ || | | | | / 18 |____|____|/ \|___| | / \|____| |____|/ 19 \( )/ \( |____|/ \( )/ 20 ' ' ' )/ ' ' 21 ' 22 ``` 23 24 DCM is a wrapper for docker-compose. It enables one click setup, build && run process for a set 25 micro services with docker. DCM also provides a couple of neat shorthand commands. 26 27 **Prerequisites** 28 * Linux Distros 29 * [Docker Engine](https://docs.docker.com/engine/installation/linux/) 30 * [Docker-Compose](https://docs.docker.com/compose/install/) 31 * Mac OS X / Windows 32 * [Docker Toolbox](https://www.docker.com/products/docker-toolbox) 33 34 OSX folks can also manually install docker: 35 36 * [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 37 * [Homebrew](http://brew.sh/) 38 * Docker Client `brew install docker` 39 * Docker Machine `brew install docker-machine` 40 * Docker Compose `brew install docker-compose` 41 42 **Supported Operating Systems** 43 44 * Mac OS X, 64bit (tested) 45 * Linux, 64bit 46 * Ubuntu (tested) 47 * Debian 48 * Mint (tested) 49 * CentOS 50 * Red Hat 51 * Fedora 52 * Gentoo 53 * FreeBSD, 64bit 54 * Windows (Cygwin), 64bit 55 56 ## Getting started 57 58 To install DCM, first checkout DCM on your local file system, and create an enhanced version 59 docker-compose config. 60 61 ```shell 62 git clone git@github.com:beanworks/dcm.git 63 # Note here the name of the config needs to be same as DCM project name 64 touch dcm/pi314.yml 65 ``` 66 67 Then add the following lines to your bashrc/zshrc 68 69 ```shell 70 export DCM_DIR="/path/to/your/dcm/dir" 71 export DCM_PROJECT="pi314" 72 73 [ -s "$DCM_DIR/dcm.sh" ] && . "$DCM_DIR/dcm.sh" 74 ``` 75 76 Source your bashrc/zshrc or profile again then you are all set. 77 78 ## Enhanced docker-compose config 79 80 DCM is based on docker-compose, so it supports all the configuration options from compose 81 (https://docs.docker.com/compose/compose-file/). In addition to those options, DCM extends 82 docker-compose with a couple of additional options. 83 84 All DCM specific options in the YAML configuration file are under `serviceName.labels`. 85 86 #### `dcm.repository` (required) 87 88 `dcm setup` command will read this option and clone the service's git repository. DCM will 89 place the repo at `$DCM_DIR/srv/$DCM_PROJECT/[service name]`. 90 91 ```yaml 92 service: 93 labels: 94 dcm.repository: git@github.com:username/repository.git 95 ``` 96 97 #### `dcm.pre_initscript` (optional) 98 99 If this option is given, `dcm run` command will run the pre-init script automatically right before `docker-compose up` process is started. 100 101 The value of the `dcm.pre_initscript` is relative to the service's folder. 102 103 ```yaml 104 service: 105 build: "./srv/project/service/" 106 labels: 107 dcm.pre_initscript: "dcm/pre-init.bash" 108 ``` 109 110 In the example above, DCM will the pre-init script `$DCM_DIR/srv/project/service/dcm/pre-init.bash`. 111 112 #### `dcm.initscript` (optional) 113 114 If this option is given, `dcm run` command will run the init script automatically right after 115 `docker-compose up` process is finished. 116 117 The value of the `dcm.initscript` is relative to the service's folder. 118 119 ```yaml 120 service: 121 build: "./srv/project/service/" 122 labels: 123 dcm.initscript: "dcm/init.bash" 124 ``` 125 126 In the example above, DCM will the init script `$DCM_DIR/srv/project/service/dcm/init.bash`. 127 128 #### `dcm.initscript_shell` (optional) 129 130 If this option is given, `dcm run` command will run the init script with the value of this shell as executable. 131 If no value is provided it defaults to `/bin/bash`. 132 133 #### `dcm.branch` (optional) 134 135 IF this option is given, DCM will switch to the git branch provided right after it clones 136 the repo during the setup process. 137 138 ```yaml 139 service: 140 labels: 141 dcm.branch: default-branch-name 142 ``` 143 144 ## One click setup, build && run 145 146 For your first time setup, run the following commands. They will checkout all the repositories 147 for different micro services, build all the images and spin up the docker containers. 148 149 ```shell 150 dcm setup && dcm run 151 ``` 152 153 Generally in your day to day development process, you should only need to run either `dcm run` 154 (shorthand version `dcm r`) or `dcm build && dcm run` (shorthand version `dcm b && dcm r`). 155 156 ## Update DCM 157 158 First, uninstall DCM from bash/zsh 159 160 ```shell 161 dcm unload 162 ``` 163 164 Then, pull the latest version DCM with git 165 166 ```shell 167 git pull 168 ``` 169 170 Lastly, source bashrc/zshrc/profile again to reinstall DCM 171 172 ```shell 173 source ~/.profile 174 # or 175 source ~/.bash_profile 176 # or 177 source ~/.bashrc 178 # or 179 zsh 180 ``` 181 182 ## Setting up multi instance 183 184 #### 1. Create YAML configuration files for multiple instances 185 186 ```shell 187 touch instance1.yml instance2.yml instance3.yml 188 ``` 189 190 Note that if you are running multi instance setup for the same set of services, you will need to 191 assign different public facing ports to in `ports` options for those containers that need to be 192 directly accessed from the host machine. 193 194 For example, if you have nginx as load balancer in instance1, instance2 and instance3, you will 195 probably need `- "8081:80"` for instance1.yml, `- "8082:80"` for instance2.yml and `- "8083:80"` 196 for instance3.yml. 197 198 #### 2. Initial setup, build && run 199 200 ```shell 201 export DCM_PROJECT=instance1 202 dcm setup && dcm run 203 204 export DCM_PROJECT=instance2 205 dcm setup && dcm run 206 207 export DCM_PROJECT=instance3 208 dcm setup && dcm run 209 ``` 210 211 Note that you can always set the env variable within the same command like this: 212 213 ```shell 214 DCM_PROJECT=instance1 dcm setup 215 DCM_PROJECT=instance1 dcm run 216 ``` 217 218 The choices are yours :) 219 220 #### 3. Subsequent rebuild && rerun 221 222 ```shell 223 export DCM_PROJECT=instance1 224 dcm build && dcm run 225 226 export DCM_PROJECT=instance2 227 dcm build && dcm run 228 229 export DCM_PROJECT=instance3 230 dcm build && dcm run 231 ``` 232 233 ## All available DCM commands 234 235 The follow menu can be viewed in command line by entering `dcm` or `dcm help` commands. 236 237 ```text 238 DCM (Docker-Compose Manager) 239 240 Usage: 241 dcm help Show this help menu. 242 dcm setup Git checkout repositories for the services that require 243 local docker build. It skips the service when the image 244 is from docker hub, or the repo's folder already exists. 245 dcm run [<args>] Run docker-compose commands. If <args> is not given, by 246 default DCM will run `docker-compose up` command. 247 <args>: up, build, start, stop, restart, pre-init, init, execute 248 dcm build Docker (re)build service images that require local build. 249 It's the shorthand version of `dcm run build` command. 250 dcm shell <service> Log into a given service container. 251 dcm purge [<type>] Remove either all the containers or all the images. If <type> 252 is not given, by default DCM will purge everything. 253 <type>: images, containers, all 254 dcm branch [<service>] Display the current git branch for the given service that 255 was built locally. 256 dcm goto [<service>] Go to the service's folder. If <service> is not given, by 257 default DCM will go to $DCM_DIR. 258 dcm update [<service>] Update DCM and(or) the given service. 259 dcm list List all the available services. 260 261 Example: 262 Initial setup 263 dcm setup 264 dcm run 265 266 Rebuild 267 dcm build 268 dcm run 269 270 Or only Rerun 271 dcm run 272 273 Log into a service's container 274 dcm shell service_name 275 ``` 276 277 ## TODOs 278 279 * Support CLI autocomplete for zsh 280 * Add working examples 281 * Containerize an app that involves a couple of micro services 282 * Create a YAML config for DCM to setup, build and run the app 283 * Test on different OS 284 * Linux Distros 285 * FreeBSD 286 * Windows Cygwin 287 288 ## Contributing 289 290 All code needs to be formatted with `gofmt`. `goimports` is more preferred as it also auto-generate 291 and format import section. 292 293 We suggest contributors use vim-go or GoSublime if you are vim lovers or sublime folks. If you use 294 neither of those editors, having a editor or IDE respects EditorConfig and automatically invoke 295 `gofmt` or `goimports` on save is highly recommended. 296 297 #### Make a development copy 298 299 Make sure you have Go 1.6+ installed and GOPATH set (https://golang.org/doc/code.html). 300 301 ```shell 302 git clone git@github.com:beanworks/dcm.git $GOPATH/src/github.com/beanworks/dcm 303 cd $GOPATH/src/github.com/beanworks/dcm 304 ``` 305 306 Run command `tree -a -I .git` you will see the following folder and file structure: 307 308 ```text 309 . 310 ├── .editorconfig 311 ├── .gitignore 312 ├── .travis.yml 313 ├── LICENSE 314 ├── Makefile 315 ├── README.md 316 ├── bin 317 │ ├── dcm-darwin-amd64 318 │ ├── dcm-freebsd-amd64 319 │ ├── dcm-linux-amd64 320 │ └── dcm-windows-amd64.exe 321 ├── dcm.sh 322 ├── src 323 │ ├── cmd.go 324 │ ├── cmd_test.go 325 │ ├── config.go 326 │ ├── config_test.go 327 │ ├── dcm.go 328 │ ├── dcm_test.go 329 │ ├── main.go 330 │ ├── util.go 331 │ └── util_test.go 332 └── srv 333 └── .gitignore 334 ``` 335 336 All the source files are located in `src` folder. 337 338 #### Running unit tests 339 340 ```shell 341 # Run the whole test suite 342 make test 343 # Run tests in verbose mode 344 make vtest 345 ``` 346 347 #### Generating test coverage report 348 349 ```shell 350 make cover 351 ``` 352 353 #### Build executables 354 355 ```shell 356 # Build development executable 357 make 358 # Run development executable 359 bin/dcm 360 # Cross compile executables for different OS 361 make cross 362 # Cleanup 363 make clean 364 # Cleanup and remove all the cross compile executables 365 make cleanall 366 ``` 367 368 ## License 369 370 Copyright (c) 2016, Beanworks Solutions Inc. <engpartnership@beanworks.com> 371 All rights reserved. 372 373 Redistribution and use in source and binary forms, with or without 374 modification, are permitted provided that the following conditions are met: 375 376 * Redistributions of source code must retain the above copyright notice, this 377 list of conditions and the following disclaimer. 378 379 * Redistributions in binary form must reproduce the above copyright notice, 380 this list of conditions and the following disclaimer in the documentation 381 and/or other materials provided with the distribution. 382 383 * Neither the name of dcm nor the names of its 384 contributors may be used to endorse or promote products derived from 385 this software without specific prior written permission. 386 387 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 388 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 389 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 390 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 391 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 392 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 393 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 394 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 395 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 396 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.