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