Merge pull request #125 from Dimrok/feature/more-examples

Add more examples.

Author: mnottale

examples/hello-world/README.md

@@ -0,0 +1,105 @@
+## The Docker voting app
+
+### Initialize project
+
+In this example, we will create a single service application that deploys a web page displaying a message.
+
+Initialize the single file project using `docker-app init -s hello-world`. A single file application contains the three sections, `metadata` corresponding `metadata.yml`, `settings` corresponding `settings.yml` and `services` corresponding `docker-compose.yml`.
+
+```bash
+$ ls -l
+-rw-r--r-- 1 README.md
+$ docker-app init -s hello-world
+$ ls -l
+-rw-r--r-- 1 README.md
+-rw-r--r-- 1 hello-world.dockerapp
+$ cat hello-world.dockerapp
+#
+# Metadata.
+#
+version: 0.1.0
+name: hello-world
+description: ""
+maintainers:
+- name: dimrok
+  email: ""
+targets:
+  swarm: true
+  kubernetes: true
+
+--
+#
+# Services.
+#
+version: "3.6"
+services: {}
+
+--
+#
+# Settings.
+#
+```
+
+Open `hello-world.dockerapp` with your favorite text editor.
+
+### Edit metadata
+
+Edit the `description` and `maintainers` fields in the metadata section.
+
+### Add variables to the compose file
+
+Add a service `hello` to the `services` section.
+
+---
+
+[hello-world.dockerapp](hello-world.dockerapp):
+```yml
+[...]
+---
+#
+# Services.
+#
+services:
+  hello:
+    image: hashicorp/http-echo
+    command: ["-text", "${text}"]
+    ports:
+      - ${port}:5678
+
+---
+[...]
+```
+
+### Give variables their default value
+
+In the settings section, add every variables with the default value you want, e.g.:
+
+---
+
+[hello-world.dockerapp](hello-world.dockerapp):
+```yml
+[...]
+---
+#
+# Settings.
+#
+port: 8080
+text: hello world!
+```
+
+### Render
+
+You can now render your application by running `docker-app render` or even personalize the rendered compose file by running `docker-app render -s text="hello user!"`.
+
+Create a `render` directory and redirect the output of `docker-app render ...` to `render/docker-compose.yml`.
+
+```bash
+$ mkdir -p render
+$ docker-app render -s text="hello user" > render/docker-compose.yml
+```
+
+### Deploy
+
+You directly deploy your application by running `docker-app deploy -s text="hello user!"` or you can use the rendered version and run `docker stack deploy render/docker-compose.yml`.
+
+`http://<ip_of_your_node>:8080` will display your message, e.g. http://127.0.0.1:8080 if you deployed locally.

examples/hello-world/hello-world.dockerapp

@@ -0,0 +1,31 @@
+#
+# Metadata.
+#
+version: 0.1.0
+name: hello-world
+description: "Hello world!"
+maintainers:
+- name: user
+  email: "[email protected]"
+targets:
+  swarm: true
+  kubernetes: true
+
+--
+#
+# Services.
+#
+version: "3.6"
+services:
+  hello:
+    image: hashicorp/http-echo
+    command: ["-text", "${text}"]
+    ports:
+      - ${port}:5678
+
+--
+#
+# Settings.
+#
+port: 8080
+text: hello world!

examples/voting-app/README.md

@@ -0,0 +1,252 @@
+## The Docker voting app
+
+### Initialize project
+
+In this example, we will create an app from the existing docker sample `example-voting-app`. First download the project [here](https://github.com/dockersamples/example-voting-app).
+
+Initialize the project using `docker-app init voting-app -c example-voting-app/docker-stack.yml`.
+
+### Edit metadata
+
+Go to `voting-app.dockerapp/` and open `metadata.yml` and fill the following fields:
+- description
+- maintainers
+
+### Add variables to the compose file
+
+Open `docker-compose.yml` and start by changing the version to `3.2` (generated docker-compose are version 3.2+ compatible). Change constants you want by variables, e.g.:
+
+Change the images used, from:
+- `dockersamples/examplevotingapp_vote:before` to `${vote.image.name}:${vote.image.tag}`
+- `dockersamples/examplevotingapp_result:before` to `${result.image.name}:${result.image.tag}`
+- `dockersamples/examplevotingapp_worker:before` to `${worker.image.name}:${worker.image.tag}`
+- `dockersamples/examplevotingapp_visualizer:before` to `${visualizer.image.name}:${visualizer.image.tag}`
+
+Change exposed ports, from:
+- `<value:5000>` to `${vote.port}`
+- `<value:5001>` to `${result.port}`
+- `<value:8080>` to `${visualizer.port}`
+
+Change default replicas, from:
+- `<value:2>` to `${vote.replicas}`
+- `<value:1>` to `${result.replicas}`
+- `<value:1>` to `${worker.replicas}`
+
+---
+
+[voting-app.dockerapp/docker-compose.yml](voting-app.dockerapp/docker-compose.yml):
+```yml
+[...]
+vote:
+    image: ${vote.image.name}:${vote.image.tag}
+    ports:
+      - ${vote.port}:80
+    networks:
+      - frontend
+    depends_on:
+      - redis
+    deploy:
+      replicas: ${vote.replicas}
+      update_config:
+        parallelism: 2
+      restart_policy:
+        condition: on-failure
+
+  result:
+    image: ${result.image.name}:${result.image.tag}
+    ports:
+      - ${result.port}:80
+    networks:
+      - backend
+    depends_on:
+      - db
+    deploy:
+      replicas: ${result.replicas}
+      update_config:
+        parallelism: 2
+        delay: 10s
+      restart_policy:
+        condition: on-failure
+
+  worker:
+    image: ${worker.image.name}:${worker.image.tag}
+    networks:
+      - frontend
+      - backend
+    deploy:
+      mode: replicated
+      replicas: ${worker.replicas}
+      labels: [APP=VOTING]
+      restart_policy:
+        condition: on-failure
+        delay: 10s
+        max_attempts: 3
+        window: 120s
+      placement:
+        constraints: [node.role == manager]
+
+  visualizer:
+    image: ${visualizer.image.name}:${visualizer.image.tag}
+    ports:
+      - ${visualizer.port}:8080
+    stop_grace_period: 1m30s
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock"
+    deploy:
+      placement:
+        constraints: [node.role == manager]
+[...]
+```
+
+### Give variables their default value
+
+Open `settings.yml` and add every variables with the default value you want, e.g.:
+
+---
+
+[voting-app.dockerapp/settings.yml](voting-app.dockerapp/settings.yml):
+```yml
+# Vote.
+vote:
+  image:
+    name: dockersamples/examplevotingapp_vote
+    tag: latest
+  port: 8080
+  replicas: 1
+
+# Result.
+result:
+  image:
+    name: dockersamples/examplevotingapp_result
+    tag: latest
+  port: 8181
+  replicas: 1
+
+# Visualizer.
+visualizer:
+  image:
+    name: dockersamples/visualizer
+    tag: latest
+  port: 8282
+
+# Worker.
+worker:
+  image:
+    name: dockersamples/examplevotingapp_worker
+    tag: latest
+  replicas: 1
+```
+
+Test your application by running `docker-app render`.
+
+### Add settings for production and development environments
+
+Create `settings/development.yml` and `settings/production.yml` and add your target-specific variables.
+
+---
+
+[voting-app.dockerapp/settings/development.yml](voting-app.dockerapp/settings/development.yml):
+```yml
+# Vote.
+vote:
+  image:
+    name: vote
+
+# Result.
+result:
+  image:
+    name: result
+```
+---
+
+[voting-app.dockerapp/settings/production.yml](voting-app.dockerapp/settings/production.yml):
+```yml
+# Vote.
+vote:
+  port: 80
+  replicas: 3
+
+# Result.
+result:
+  port: 80
+  replicas: 5
+```
+
+### Wrap everything in a Makefile
+
+Add a Makefile to simplify rendering, deploying and killing your app.
+
+---
+
+[voting-app.dockerapp/Makefile](voting-app.dockerapp/Makefile):
+```Makefile
+# Input.
+SETTINGS_DIR ?= settings
+APP_NAME := voting-app
+
+# Output.
+DEVELOPMENT_DIR := build/development
+PRODUCTION_DIR := build/production
+PACK := $(APP_NAME).pack
+
+#
+# Cleanup.
+#
+cleanup/production:
+	@rm -rf $(PRODUCTION_DIR)
+
+cleanup/development:
+	@rm -rf $(DEVELOPMENT_DIR)
+
+cleanup: cleanup/production cleanup/development
+
+#
+# Render.
+#
+render/production: cleanup/production
+	@mkdir -p $(PRODUCTION_DIR)
+	docker-app render -f $(SETTINGS_DIR)/production.yml > $(PRODUCTION_DIR)/docker-compose.yml
+
+render/development: cleanup/development
+	@mkdir -p $(DEVELOPMENT_DIR)
+	docker-app render -f $(SETTINGS_DIR)/development.yml > $(DEVELOPMENT_DIR)/docker-compose.yml
+
+render: render/production render/development
+
+#
+# Stop.
+#
+stop/production:
+	docker stack rm ${APP_NAME}
+
+stop/development:
+	docker stack rm ${APP_NAME}-dev
+
+stop: stop/production stop/development
+
+#
+# Deploy.
+#
+deploy/production: render/production stop/production
+	docker-app deploy -f $(SETTINGS_DIR)/production.yml
+
+deploy/development: render/development stop/development
+	docker-app deploy -f $(SETTINGS_DIR)/development.yml
+
+#
+# Pack.
+#
+pack:
+	docker-app pack -o $(PACK)
+
+#
+# Helm.
+#
+helm/production:
+	docker-app helm -f $(SETTINGS_DIR)/production.yml
+
+helm/development:
+	docker-app helm -f $(SETTINGS_DIR)/development.yml
+```
+
+You can add more commands, depending on your needs.