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  ```