github.com/docker/app@v0.9.1-beta3.0.20210611140623-a48f773ab002/examples/hello-world/README.md (about)

     1  # Example: Hello World
     2  
     3  In this example, we will create a Docker App which is a single service application deploying a web
     4  server with a configurable text message.
     5  
     6  ## Creating an App definition
     7  
     8  First, we create an App definition using the `docker app init` command:
     9  
    10  ```shell
    11  $ docker app init hello-world
    12  Created "hello-world.dockerapp"
    13  $ tree
    14  .
    15  ├── hello-world.dockerapp
    16      ├── docker-compose.yml
    17      ├── metadata.yml
    18      └── parameters.yml
    19  ```
    20  
    21  A new folder named `hello-world.dockerapp` now exists, which contains three YAML documents:
    22  * metadata
    23  * a [Compose file](https://docs.docker.com/compose/compose-file/)
    24  * parameters to be used at runtime
    25  
    26  The `metadata.yml` file should display as follows:
    27  
    28  ```yaml
    29  # Version of the application
    30  version: 0.1.0
    31  # Name of the application
    32  name: hello-world
    33  # A short description of the application
    34  description:
    35  # List of application maintainers with name and email for each
    36  maintainers:
    37    - name: user
    38      email:
    39  ```
    40  
    41  The `docker-compose.yml` should contain the following:
    42  
    43  ```yaml
    44  version: "3.6"
    45  services: {}
    46  ```
    47  
    48  The `parameters.yml`file should be empty.
    49  
    50  ## Editing App definition
    51  
    52  Open `hello-world.dockerapp` with your favorite text editor.
    53  
    54  ### Editing the metadata
    55  
    56  Open the `metadata.yml` file and edit the `description` and `maintainers` fields in the metadata section.
    57  
    58  ### Editing the list of services
    59  
    60  Open the `docker-compose.yml` file and add a `hello` service to the `services` section.
    61  
    62  ```yaml
    63  version: "3.6"
    64  services:
    65    hello:
    66      image: hashicorp/http-echo
    67      command: ["-text", "${text}"]
    68      ports:
    69        - ${port}:5678
    70  ```
    71  
    72  ### Editing the parameters
    73  
    74  In the `parameters.yml` file, add variables with their default value:
    75  
    76  ```yaml
    77  port: 8080
    78  text: Hello, World!
    79  ```
    80  
    81  ## Building an App image
    82  
    83  Next, build an App image from the App definition we have created:
    84  
    85  ```shell
    86  $ docker app build . -f hello-world.dockerapp -t myrepo/hello:0.1.0
    87  [+] Building 0.6s (6/6) FINISHED
    88  (...) (Build output)
    89  sha256:7b48c121fcafa0543b7e88c222304f9fada9911011694b041a7f0e096536db6c
    90  ```
    91  
    92  At this point, an App image with the `myrepo/hello:1.0.1` tag has been built from the `hello-world.dockerapp` App definition. This immutable App image includes all the service images at fixed versions that you can run or share.
    93  
    94  ## Inspecting an App image
    95  
    96  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.
    97  
    98  ```shell
    99  $ docker  app image inspect myrepo/hello-world:0.1.0 --pretty
   100  version: 0.1.0
   101  name: hello-world
   102  description: This is an Hello World example
   103  maintainers:
   104  - name: user
   105    email: user@email.com
   106  
   107  SERVICE   REPLICAS   PORTS   IMAGE
   108  hello     1          8080    docker.io/hashicorp/http-echo:latest@sha256:ba27d460cd1f22a1a4331bdf74f4fccbc025552357e8a3249c40ae216275de96
   109  
   110  PARAMETER VALUE
   111  port      8080
   112  text      Hello, World!
   113  ```
   114  
   115  ## Sharing the App
   116  
   117  Share your App image by pushing it to a container registry such as Docker Hub.
   118  
   119  ```shell
   120  $ docker app push myrepo/hello:0.1.0
   121  ```
   122  
   123  ## Running the App
   124  
   125  Now run your App:
   126  
   127  ```shell
   128  $ docker app run myrepo/hello:0.1.0  --name myhelloworld
   129  Creating network myhelloworld_default
   130  Creating service myhelloworld_hello
   131  App "myhelloworld" running on context "default"
   132  ```
   133  
   134  You can specify the Docker endpoint where an application is installed using a context. By default, your App will run on the currently active context. You can select another context with the docker context use command, and the docker app run command will thereafter run your app on this particular context.
   135  
   136  Next, you can check the list of running Apps:
   137  
   138  ```shell
   139  $ docker app ls
   140  RUNNING APP    APP NAME            LAST ACTION   RESULT    CREATED              MODIFIED             REFERENCE
   141  myhelloworld   hello-world (0.1.0) install       success   About a minute ago   About a minute ago   docker.io/myrepo/hello-world:0.1.0
   142  ```
   143  
   144  ## Inspecting a running App
   145  
   146  Finally you can get detailed information about a running App using the `docker app inspect` command. Note that the `--pretty` option allows to get a human friendly output rather than the default JSON output.
   147  
   148  ```shell
   149  $ docker app inspect myhelloworld --pretty
   150  Running App:
   151    Name: myhelloworld
   152    Created: 3 minutes ago
   153    Modified: 3 minutes ago
   154    Revision: 01DSQMWWABCM27K3FWSCES3H76
   155    Last Action: install
   156    Result: success
   157    Ochestrator: swarm
   158  
   159  App:
   160    Name: hello-world
   161    Version: 0.1.0
   162    Image Reference: docker.io/myrepo/hello-world:0.1.0
   163  
   164  Parameters:
   165    port: "8080"
   166    text: Hello, World!
   167  
   168  ID            NAME                MODE        REPLICAS  IMAGE                PORTS
   169  mocfqnkadxw3  myhelloworld_hello  replicated  1/1       hashicorp/http-echo  *:8080->5678/tcp
   170  ```
   171  
   172  Finally, remove the current running App using the `docker app rm`command.
   173  
   174  ```shell
   175  $ docker app rm myhelloworld
   176  Removing service myhelloworld_hello
   177  Removing network myhelloworld_default
   178  ```