github.com/simonferquel/app@v0.6.1-0.20181012141724-68b7cccf26ac/README.md (about) 1 # Docker Application Packages 2 3 An *experimental* utility to help make Compose files more reusable and sharable. 4 5 6 ## The problem application packages solve 7 8 Compose files do a great job of describing a set of related services. Not only are Compose files easy to write, they are generally easy to read as well. However, a couple of problems often emerge: 9 10 1. You have several environments where you want to deploy the application, with small configuration differences 11 2. You have lots of similar applications 12 13 Fundamentally, Compose files are not easy to share between concerns. Docker Application Packages aim to solve these problems and make Compose more useful for development _and_ production. 14 15 ## Looking at an example 16 17 Let's take the following Compose file. It launches an HTTP server which prints the specified text when hit on the configured port. 18 19 ```yaml 20 version: '3.2' 21 services: 22 hello: 23 image: hashicorp/http-echo 24 command: ["-text", "hello world"] 25 ports: 26 - 5678:5678 27 ``` 28 29 With `docker-app` installed let's create an Application Package based on this Compose file: 30 31 ```bash 32 $ docker-app init --single-file hello 33 $ ls 34 docker-compose.yml 35 hello.dockerapp 36 ``` 37 38 We created a new file `hello.dockerapp` that contains three YAML documents: 39 - metadatas 40 - the Compose file 41 - settings for your application 42 43 It should look like this: 44 45 ```yaml 46 version: 0.1.0 47 name: hello 48 description: "" 49 namespace: "" 50 maintainers: 51 - name: yourusername 52 email: "" 53 54 --- 55 version: '3.2' 56 services: 57 hello: 58 image: hashicorp/http-echo 59 command: ["-text", "hello world"] 60 ports: 61 - 5678:5678 62 63 --- 64 {} 65 ``` 66 67 Let's edit the settings section and add the following default values for our application: 68 69 ```yaml 70 port: 5678 71 text: hello development 72 version: latest 73 ``` 74 75 Then modify the Compose file section in `hello.dockerapp`, adding in the variables. 76 77 ```yaml 78 version: '3.2' 79 services: 80 hello: 81 image: hashicorp/http-echo:${version} 82 command: ["-text", "${text}"] 83 ports: 84 - ${port}:5678 85 ``` 86 87 Finally you can test everything is working, by rendering the Compose file with the provided default values. 88 89 ``` 90 $ docker-app render 91 version: "3.2" 92 services: 93 hello: 94 command: 95 - -text 96 - hello development 97 image: hashicorp/http-echo:latest 98 ports: 99 - mode: ingress 100 target: 5678 101 published: 5678 102 protocol: tcp 103 ``` 104 105 You can then use that Compose file like any other. You could save it to disk or pipe it straight to `docker stack` or `docker-compose` to launch the application. 106 107 ``` 108 $ docker-app render | docker-compose -f - up 109 ``` 110 111 This is where it gets interesting. We can override those settings at runtime, using the `--set` option. Let's specify different option and run `render` again: 112 113 ``` 114 $ docker-app render --set version=0.2.3 --set port=4567 --set text="hello production" 115 version: "3.2" 116 services: 117 hello: 118 command: 119 - -text 120 - hello production 121 image: hashicorp/http-echo:0.2.3 122 ports: 123 - mode: ingress 124 target: 5678 125 published: 4567 126 protocol: tcp 127 ``` 128 129 If you prefer you can create a standalone configuration file to store those settings. Let's create `prod.yml` with the following contents: 130 131 ```yaml 132 version: 0.2.3 133 text: hello production 134 port: 4567 135 ``` 136 137 You can then run using that configuration file like so: 138 139 ``` 140 $ docker-app render -f prod.yml 141 ``` 142 143 144 More examples are available in the [examples](examples) directory. 145 146 ## Installation 147 148 Pre-built binaries are available on [GitHub releases](https://github.com/docker/app/releases) for Windows, Linux and macOS. 149 150 ```bash 151 wget https://github.com/docker/app/releases/download/v0.6.0/docker-app-linux.tar.gz 152 tar xf docker-app-linux.tar.gz 153 cp docker-app-linux /usr/local/bin/docker-app 154 ``` 155 156 **Note:** To use Application Packages as images (i.e.: `save`, `push`, or `deploy` when package is not present locally) on Windows, one must be in Linux container mode. 157 158 ## Integrating with Helm 159 160 `docker-app` comes with a few other helpful commands as well, in particular the ability to create Helm Charts from your Docker Applications. This can be useful if you're adopting Kubernetes, and standardising on Helm to manage the lifecycle of your application components, but want to maintain the simplicity of Compose when writing you applications. This also makes it easy to run the same applications locally just using Docker, if you don't want to be running a full Kubernetes cluster. 161 162 ``` 163 $ docker-app helm 164 ``` 165 166 This will create a folder, `<my-application-name>.chart`, in the current directory. The folder contains the required `Chart.yaml` file and templates describing the `stack` Kubernetes object based on the Compose file in your application. 167 168 _Note that this requires the Compose Kubernetes controller available in Docker for Windows and Docker for Mac, and in Docker Enterprise Edition._ 169 170 ### Helm chart for Docker EE 2.0 171 172 In order to create a helm chart that is compatible with version 2.0 of Docker Enterprise Edition, you will need to use the `--stack-version` flag to create a compatible version of the helm chart using `v1beta1` like so: 173 174 ```bash 175 $ docker-app helm --stack-version=v1beta1 176 ``` 177 178 ## Single file or directory representation 179 180 If you prefer having the three core documents in separate YAML files, omit the `-s` / `--single-file` option to 181 the `docker-app init` command. This will create a directory instead of a single file, containing 182 `metadata.yml`, `docker-compose.yml` and `settings.yml`. 183 184 Converting between the two formats can be achieved by using the `docker-app split` and `docker-app merge` commands. 185 186 Note that you cannot store attachments in the single file format. If you want to use attachments you should use the directory format. 187 188 ## Attachments (Storing additional files) 189 190 If you want to store additional files in the application package, such as `prod.yml`, `test.yml` or other config files, use the directory format and simply place these files inside the *.dockerapp/ directory. These will be bundled into the package when using `docker-app push` 191 192 ## Sharing your application on the Hub 193 194 You can push any application to the Hub using `docker-app push`: 195 196 ``` bash 197 $ docker-app push --namespace myhubuser --tag latest 198 ``` 199 200 This command will push to the Hub an image named `myhubuser/hello.dockerapp:latest`. 201 202 If you omit the `--tag latest` argument, this command uses the application `version` defined in `metadata.yml` as the tag. 203 If you omit the `--namespace myhubuser` argument, this command uses the application `namespace` defined in `metadata.yml` as the image namespace. 204 205 All `docker-app` commands accept an image name as input, which means you can run on a different host: 206 207 ``` bash 208 $ docker-app inspect myhubuser/hello 209 ``` 210 211 ## Forking an existing image 212 213 Found an app on a remote registry you'd like to modify to better suit your needs? Use the `fork` subcommand: 214 215 ```bash 216 $ docker-app fork remote/hello.dockerapp:1.0.0 mine/hello2 -m "Bob Dylan:bob@aol.com" 217 ``` 218 219 This command will create a local, editable copy of the app on your system. By default, the copy is created inside the current directory; you may use the `--path` flag to configure a different destination. 220 221 For example, the following will create the `/opt/myapps/hello2.dockerapp` folder containing the forked app's files: 222 223 ```bash 224 $ docker-app fork remote/hello.dockerapp:1.0.0 mine/hello2 --path /opt/myapps 225 ``` 226 227 ## Next steps 228 229 We have lots of ideas for making Compose-based applications easier to share and reuse, and making applications a first-class part of the Docker toolchain. Please let us know what you think about this initial release and about any of the ideas below: 230 231 * Introducing environments to the settings file 232 * Docker images which launch the application when run 233 * Built-in commands for running applications 234 * Saving required images into the application artifact to support offline installation 235 * Signing applications with notary 236 237 238 ## Usage 239 240 ``` 241 $ docker-app 242 243 Usage: docker-app [OPTIONS] COMMAND 244 245 Docker Application Packages 246 247 Options: 248 -D, --debug Enable debug mode 249 -H, --host list Daemon socket(s) to connect to 250 -l, --log-level string Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info") 251 --tls Use TLS; implied by --tlsverify 252 --tlscacert string Trust certs signed only by this CA (default "/Users/chris/.docker/ca.pem") 253 --tlscert string Path to TLS certificate file (default "/Users/chris/.docker/cert.pem") 254 --tlskey string Path to TLS key file (default "/Users/chris/.docker/key.pem") 255 --tlsverify Use TLS and verify the remote 256 -v, --version Print version information 257 258 Commands: 259 completion Generates completion scripts for the specified shell (bash or zsh) 260 deploy Deploy or update an application 261 fork Create a fork of an existing application to be modified 262 helm Generate a Helm chart 263 init Start building a Docker application 264 inspect Shows metadata, settings and a summary of the compose file for a given application 265 merge Merge a multi-file application into a single file 266 push Push the application to a registry 267 render Render the Compose file for the application 268 split Split a single-file application into multiple files 269 validate Checks the rendered application is syntactically correct 270 version Print version information 271 272 Run 'docker-app COMMAND --help' for more information on a command. 273 ``` 274 275 ## Shell completion 276 277 ### Bash 278 279 Load the docker-app completion code for bash into the current shell: 280 ```sh 281 $ source <(docker-app completion bash) 282 ``` 283 Set the docker-app completion code for bash to autoload on startup in your ~/.bashrc, ~/.profile or ~/.bash_profile: 284 ```sh 285 source <(docker-app completion bash) 286 ``` 287 **Note**: `bash-completion` is needed. 288 289 ### Zsh 290 291 Load the docker-app completion code for zsh into the current shell 292 ```sh 293 $ source <(docker-app completion zsh) 294 ``` 295 Set the docker-app completion code for zsh to autoload on startup in your ~/.zshrc 296 ```sh 297 source <(docker-app completion zsh) 298 ```