github.com/docker/app@v0.9.1-beta3.0.20210611140623-a48f773ab002/examples/voting-app/README.md (about) 1 # Example: Voting App 2 3 In this example, we will create a Docker App from the existing Docker 4 sample `example-voting-app` from 5 [here](https://github.com/dockersamples/example-voting-app). 6 7 ## Creating an App definition 8 9 First, create an App definition from an existing [Compose file](https://docs.docker.com/compose/compose-file/) using the `docker app init` command: 10 11 ```shell 12 $ docker app init voting-app --compose-file docker-compose.yml 13 Created "voting-app.dockerapp" 14 $ tree 15 . 16 ├── docker-compose.yml 17 ├── voting-app.dockerapp 18 ├── docker-compose.yml 19 ├── metadata.yml 20 └── parameters.yml 21 ``` 22 23 ### Editing metadata 24 25 In the `voting-app.dockerapp` directory, open the `metadata.yml` file and fill the "description" and "maintainers" fields. 26 27 ### Editing services 28 29 Now we are going to add some variables to our Compose file. 30 31 To do so, open the `docker-compose.yml` file in the `voting-app.dockerapp` directory, and edit the following values: 32 33 * In the `vote` service, change the port from `"5000:80"` to `${vote.port}:80` 34 * In the `result` service, change the port from `"5001:80"` to `${result.port}:80` 35 * In the `visualizer` service, change the port from `"8080:8080"` to `${visualizer.port}:8080` 36 * In the `vote` service, change the replicas from `2` to `${vote.replicas}` 37 38 The `voting-app.dockerapp/docker-compose.yml` file should now look like this: 39 40 ```yaml 41 version: "3.6" 42 43 services: 44 redis: 45 image: redis:alpine 46 ports: 47 - "6379:6379" 48 db: 49 image: postgres:9.4 50 ports: 51 - "5432:5432" 52 vote: 53 image: dockersamples/examplevotingapp_vote:before 54 ports: 55 - "${vote.port}:80" 56 deploy: 57 replicas: ${vote.replicas} 58 result: 59 image: dockersamples/examplevotingapp_result:before 60 ports: 61 - "${result.port}:80" 62 worker: 63 image: dockersamples/examplevotingapp_worker 64 ``` 65 66 ### Set default parameters 67 68 Open the `voting-app.dockerapp/parameters.yml` file and define a default value for each variable you created in the `docker-compose.yml`file in the previous step. 69 70 ```yaml 71 vote: 72 port: 5000 73 replicas: 2 74 result: 75 port: 5001 76 ``` 77 78 ## Building an App image 79 80 Next, build an App image from the App definition we have created: 81 82 ```shell 83 $ docker app build . -f voting-app.dockerapp -t voting-app:0.1.0 84 [+] Building 0.6s (6/6) FINISHED 85 (...) (Build output) 86 sha256:46379a70af728aca32c993373b4a52655fde106953dd5a4e56aed05cde202530 87 ``` 88 89 ## Inspecting an App image 90 91 Now let's get detailed information about the App image we just built using the `docker app image inspect` command. Note that the `--pretty` option allows to get a human friendly output rather than the default JSON output. 92 93 ```shell 94 $ docker app image inspect voting-app:0.1.0 --pretty 95 name: voting-app 96 description: Dogs or cats? 97 maintainers: 98 - name: user 99 email: user@email.com 100 101 102 SERVICE REPLICAS PORTS IMAGE 103 db 1 5432 docker.io/library/postgres:9.4@sha256:c2561ced3d8b82a306fe09b18f9948e2d2ce8b47600125d2c7895ca3ea3a9a44 104 redis 1 6379 docker.io/library/redis:alpine@sha256:27e139dd0476133961d36e5abdbbb9edf9f596f80cc2f9c2e8f37b20b91d610d 105 result 1 5001 docker.io/dockersamples/examplevotingapp_result:before@sha256:83b568996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463 106 vote 2 5000 docker.io/dockersamples/examplevotingapp_vote:before@sha256:8e64b18b2c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6 107 worker 1 docker.io/dockersamples/examplevotingapp_worker:latest@sha256:55753a7b7872d3e2eb47f146c53899c41dcbe259d54e24b3da730b9acbff50a1 108 109 PARAMETER VALUE 110 result.port 5001 111 vote.port 5000 112 vote.replicas 2 113 ``` 114 115 Service images inside of a Docker App image are immutable, meaning that the App version ties to a fixed list of service images, and you can see it here: check the service image information in the `docker app image inspect`output above; you can see that each service (`db`, `redis`, `result`, `vote` and `worker`) has a unique service image associated at build time. 116 117 *Notes:* 118 * *the service image unicity is guaranteed by the tag using a digest (sha256 value)* 119 * *the "." in the Parameter section indicates hierarchy* 120 121 ## Running the App 122 123 Now, run the App using the `docker app run`command. 124 125 ```shell 126 $ docker app run voting-app:0.1.0 --name myvotingapp 127 Creating network myvotingapp_default 128 Creating service myvotingapp_vote 129 Creating service myvotingapp_result 130 Creating service myvotingapp_worker 131 Creating service myvotingapp_redis 132 Creating service myvotingapp_db 133 App "myvotingapp" running on context "default" 134 ``` 135 136 You can get detailed information about the running App using the `docker app inspect` command. 137 138 ```shell 139 docker app inspect myvotingapp --pretty 140 Running App: 141 Name: myvotingapp 142 Created: 43 seconds ago 143 Modified: 33 seconds ago 144 Revision: 01DT6PJ43CCNWEH4XRMPGSX82A 145 Last Action: install 146 Result: success 147 Ochestrator: swarm 148 149 App: 150 Name: voting-app 151 Version: 0.1.0 152 Image Reference: docker.io/library/voting-app:0.1.0 153 154 Parameters: 155 result.port: "5001" 156 vote.port: "5000" 157 vote.replicas: "2" 158 159 ID NAME MODE REPLICAS IMAGE PORTS 160 brin0j269w9z myvotingapp_redis replicated 1/1 redis *:6379->6379/tcp 161 fdzie3g4712m myvotingapp_worker replicated 1/1 dockersamples/examplevotingapp_worker 162 mb37mavvj55r myvotingapp_result replicated 1/1 dockersamples/examplevotingapp_result *:5001->80/tcp 163 vk26ecrvycs8 myvotingapp_db replicated 1/1 postgres *:5432->5432/tcp 164 yt011xo3yc81 myvotingapp_vote replicated 2/2 dockersamples/examplevotingapp_vote *:5000->80/tcp 165 ``` 166 167 ## Adding parameters file for another environment 168 169 Create a `prod` folder to store the parameters you would use for 170 production. Create a new `prod-parameters.yml` file in the `prod` folder. 171 172 ```shell 173 $ mkdir prod 174 $ tree 175 . 176 ├── docker-compose.yml 177 ├── prod 178 │ └── prod-parameters.yml 179 └── voting-app.dockerapp 180 ├── docker-compose.yml 181 ├── metadata.yml 182 └── parameters.yml 183 ``` 184 185 Open it in a text editor and set the values you would like to use for production, for example: 186 187 ```yaml 188 vote: 189 port: 8080 190 replicas: 5 191 result: 192 port: 9000 193 ``` 194 195 ## Update the running App using production parameters 196 197 Now, we will update the running App to overwrite the current parameters with the production parameters we created at the previous step. 198 199 ```shell 200 $ docker app update myvotingapp --parameters-file prod/prod-parameters.yml 201 Updating service myvotingapp_vote (id: os3s3g4pkmqwd3s1nnk9cmeq7) 202 Updating service myvotingapp_result (id: y4y4m60imchx0pm7vlehnip8s) 203 Updating service myvotingapp_worker (id: ergdynkn9u03pz1xe461me1yq) 204 Updating service myvotingapp_redis (id: fimso41ha11xkqqj19j1ev13o) 205 Updating service myvotingapp_db (id: ub3vxjiwo1zxc75vzj5mu2vqm) 206 ``` 207 208 Run again the `docker app inspect` command, check the parameter section in the output and you'll see the parameter values have changed. 209 210 ```shell 211 docker app inspect myvotingapp --pretty 212 Running App: 213 Name: myvotingapp 214 Created: 15 minutes ago 215 Modified: 1 minute ago 216 Revision: 01DT6QN7D2R3VKM2QPAQCZ3R1F 217 Last Action: upgrade 218 Result: success 219 Ochestrator: swarm 220 221 App: 222 Name: voting-app 223 Version: 0.1.0 224 Image Reference: docker.io/library/voting-app:0.1.0 225 226 Parameters: 227 result.port: "9000" 228 vote.port: "8080" 229 vote.replicas: "5" 230 231 ID NAME MODE REPLICAS IMAGE PORTS 232 ergdynkn9u03 myvotingapp_worker replicated 1/1 dockersamples/examplevotingapp_worker 233 fimso41ha11x myvotingapp_redis replicated 1/1 redis *:6379->6379/tcp 234 os3s3g4pkmqw myvotingapp_vote replicated 5/5 dockersamples/examplevotingapp_vote *:8080->80/tcp 235 ub3vxjiwo1zx myvotingapp_db replicated 1/1 postgres *:5432->5432/tcp 236 y4y4m60imchx myvotingapp_result replicated 1/1 dockersamples/examplevotingapp_result *:9000->80/tcp 237 ``` 238 239 Finally, remove the current running App using the `docker app rm`command. 240 241 ```shell 242 $ docker app rm myvotingapp 243 Removing service myvotingapp_db 244 Removing service myvotingapp_redis 245 Removing service myvotingapp_result 246 Removing service myvotingapp_vote 247 Removing service myvotingapp_worker 248 Removing network myvotingapp_default 249 ```