Improve deploy apps with UCP

_data/toc.yaml

@@ -1685,10 +1685,8 @@ manuals:
       section:
       - title: Deploy a single service
         path: /ee/ucp/swarm/
-      - title: Deploy an app from the UI
+      - title: Deploy a multi-service app
-        path: /ee/ucp/swarm/deploy-from-ui/
+        path: /ee/ucp/swarm/deploy-multi-service-app/
-      - title: Deploy an app from the CLI
-        path: /ee/ucp/swarm/deploy-from-cli/
       - title: Deploy application resources to a collection
         path: /ee/ucp/swarm/deploy-to-collection/
       - title: Use secrets in your services

ee/ucp/swarm/deploy-from-cli.md

@@ -1,193 +0,0 @@
----
-title: Deploy an app from the CLI
-description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane.
-keywords: ucp, deploy, application, stack, service, compose
-redirect_from:
-  - /ee/ucp/user/services/deploy-app-cli/
-ui_tabs:
-- version: ucp-3.0
-  orlower: true
----
-{% if include.version=="ucp-3.0" %}
-
-With Docker Universal Control Plane you can deploy your apps from the CLI,
-using `docker-compose.yml` files. In this example, we're going to deploy an
-application that allows users to vote on whether they prefer cats or dogs.
-
-## Get a client certificate bundle
-
-Docker UCP secures your Docker cluster with
-[role-based access control](../authorization/index.md),
-so that only authorized users can deploy applications. To be able to run Docker
-commands on a cluster managed by UCP, you need to configure your Docker CLI
-client to authenticate to UCP using client certificates.
-[Learn how to set your CLI to use client certificates](../user-access/cli.md).
-
-## Deploy the voting application
-
-The application we're going to deploy is composed of several services:
-
-* `vote`: The web application that presents the voting interface via port 5000
-* `result`: A web application that displays the voting results via port 5001
-* `visualizer`: A web application that shows a map of the deployment of the
-  various services across the available nodes via port 8080
-* `redis`: Collects raw voting data and stores it in a key/value queue
-* `db`: A PostgreSQL service which provides permanent storage on a host volume
-* `worker`: A background service that transfers votes from the queue to permanent storage
-
-After setting up your Docker CLI client to authenticate using client certificates,
-create a file named `docker-compose.yml` with the following contents:
-
-```yaml
-version: "3"
-services:
-
-  redis:
-    image: redis:alpine
-    ports:
-      - "6379"
-    networks:
-      - frontend
-    deploy:
-      replicas: 2
-      update_config:
-        parallelism: 2
-        delay: 10s
-      restart_policy:
-        condition: on-failure
-  db:
-    image: postgres:9.4
-    volumes:
-      - db-data:/var/lib/postgresql/data
-    networks:
-      - backend
-    deploy:
-      placement:
-        constraints: [node.role == manager]
-  vote:
-    image: manomarks/examplevotingapp_vote
-    ports:
-      - 5000:80
-    networks:
-      - frontend
-    depends_on:
-      - redis
-    deploy:
-      replicas: 6
-      update_config:
-        parallelism: 2
-      restart_policy:
-        condition: on-failure
-  result:
-    image: manomarks/examplevotingapp_result
-    ports:
-      - 5001:80
-    networks:
-      - backend
-    deploy:
-      replicas: 2
-      update_config:
-        parallelism: 2
-        delay: 10s
-      restart_policy:
-        condition: on-failure
-
-  worker:
-    image: manomarks/examplevotingapp_worker
-    networks:
-      - frontend
-      - backend
-    deploy:
-      mode: replicated
-      replicas: 2
-      labels: [APP=VOTING]
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-        max_attempts: 3
-        window: 120s
-      placement:
-        constraints: [node.role == worker]
-  visualizer:
-    image: manomarks/visualizer
-    ports:
-      - "8080:8080"
-    stop_grace_period: 1m30s
-    volumes:
-      - "/var/run/docker.sock:/var/run/docker.sock"
-
-networks:
-  frontend:
-  backend:
-
-volumes:
-  db-data:
-```
-
->  You can define services in this YAML file that feature a `deploy:` key, which
->  schedules the containers on certain nodes, defines their restart behavior,
->  configures the number of replicas, and so on. These features are provided
->  by the Compose V3 file format.
->  [Learn about Compose files](/compose/compose-file/).
-
-In your command line, navigate to the place where you've created the
-`docker-compose.yml` file and deploy the application to UCP by running `docker
-stack deploy` and giving the application a name, like "VotingApp":
-
-```bash
-docker stack deploy --compose-file docker-compose.yml VotingApp
-```
-
-Test that the voting app is up and running using `docker stack services`:
-
-```bash
-docker stack services VotingApp
-
-ID            NAME                  MODE        REPLICAS  IMAGE
-df7uqiqyqi1n  VotingApp_visualizer  replicated  1/1       manomarks/visualizer:latest
-f185w6xnjibe  VotingApp_result      replicated  2/2       manomarks/examplevotingapp_result:latest
-hh8qzlrjsgyl  VotingApp_redis       replicated  2/2       redis:alpine
-hyvo9xfbzoat  VotingApp_db          replicated  1/1       postgres:9.4
-op3z6z5ri4k3  VotingApp_worker      replicated  1/2       manomarks/examplevotingapp_worker:latest
-umoqinuwegzj  VotingApp_vote        replicated  6/6       manomarks/examplevotingapp_vote:latest
-```
-
-As you saw earlier, a service called `VotingApp_visualizer` was deployed and
-published to port 8080. Visiting that port accesses the running instance of
-the visualizer service in your browser, which shows a map of how this application
-was deployed:
-
-![Screenshot of visualizer](../images/deployed_visualizer_detail.png){: .with-border}
-
-Here you can see some of the characteristics of the deployment specification
-from the Compose file in play. For example, the manager node is running the
-PostgreSQL container, as configured by setting `[node.role == manager]` as a
-constraint in the `deploy` key for the `db` service.
-
-## Pull images with stack deploy
-
-Let `docker stack deploy` handle any image pulls for you, instead of using
-`docker pull`. This way, your deployment won't try to pull from nodes that
-are down. Also, when new nodes are added to the cluster, images are pulled
-automatically.
-
-## Cleanup
-
-When you're all done, you can take down the entire stack by using `docker stack
-rm`:
-
-```bash
-docker stack rm VotingApp
-
-Removing service VotingApp_visualizer
-Removing service VotingApp_result
-Removing service VotingApp_redis
-Removing service VotingApp_db
-Removing service VotingApp_worker
-Removing service VotingApp_vote
-Removing network VotingApp_backend
-Removing network VotingApp_frontend
-Removing network VotingApp_default
-```
-
-{% endif %}

ee/ucp/swarm/deploy-from-ui.md

@@ -1,183 +0,0 @@
----
-title: Deploy an app from the UI
-description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane.
-keywords: ucp, deploy, application, stack, service, compose
-redirect_from:
-  - /ee/ucp/user/services/
-ui_tabs:
-- version: ucp-3.0
-  orlower: true
-next_steps:
-- path: deploy-from-cli/
-  title: Deploy an app from the CLI
----
-{% if include.version=="ucp-3.0" %}
-
-With Docker Universal Control Plane you can deploy applications from the UI
-using `docker-compose.yml` files. In this example, we're going to deploy an
-application that allows users to vote on whether they prefer cats or dogs. 😺 🐶
-
-## Deploy the voting application
-
-The application we're going to deploy is composed of several services:
-
-* `vote`: The web application that presents the voting interface via port 5000
-* `result`: A web application that displays the voting results via port 5001
-* `visualizer`: A web application that shows a map of the deployment of the
-  various services across the available nodes via port 8080
-* `redis`: Collects raw voting data and stores it in a key/value queue
-* `db`: A PostgreSQL service which provides permanent storage on a host volume
-* `worker`: A background service that transfers votes from the queue to permanent storage
-
-In your browser, log in to the UCP web UI, and navigate to the
-**Stacks** page. Click **Create Stack** to deploy a new application.
-
-Give the application a name, like "VotingApp", and in the **Mode** field,
-select **Services**.
-
-Paste the following YAML into the **COMPOSE.YML** editor:
-
-```yaml
-version: "3"
-services:
-
-  redis:
-    image: redis:alpine
-    ports:
-      - "6379"
-    networks:
-      - frontend
-    deploy:
-      replicas: 2
-      update_config:
-        parallelism: 2
-        delay: 10s
-      restart_policy:
-        condition: on-failure
-  db:
-    image: postgres:9.4
-    volumes:
-      - db-data:/var/lib/postgresql/data
-    networks:
-      - backend
-    deploy:
-      placement:
-        constraints: [node.role == manager]
-  vote:
-    image: manomarks/examplevotingapp_vote
-    ports:
-      - 5000:80
-    networks:
-      - frontend
-    depends_on:
-      - redis
-    deploy:
-      replicas: 6
-      update_config:
-        parallelism: 2
-      restart_policy:
-        condition: on-failure
-  result:
-    image: manomarks/examplevotingapp_result
-    ports:
-      - 5001:80
-    networks:
-      - backend
-    deploy:
-      replicas: 2
-      update_config:
-        parallelism: 2
-        delay: 10s
-      restart_policy:
-        condition: on-failure
-
-  worker:
-    image: manomarks/examplevotingapp_worker
-    networks:
-      - frontend
-      - backend
-    deploy:
-      mode: replicated
-      replicas: 2
-      labels: [APP=VOTING]
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-        max_attempts: 3
-        window: 120s
-      placement:
-        constraints: [node.role == worker]
-  visualizer:
-    image: manomarks/visualizer
-    ports:
-      - "8080:8080"
-    stop_grace_period: 1m30s
-    volumes:
-      - "/var/run/docker.sock:/var/run/docker.sock"
-
-networks:
-  frontend:
-  backend:
-
-volumes:
-  db-data:
-```
-
-![](../images/deploy-app-ui-1.png){: .with-border}
-
-> When "Services" is selected, you can define services in this YAML file that
-have a `deploy:` key, which schedules the containers on certain nodes, defines
-their restart behavior, configures the number of replicas, and so on. These
-features are provided by the Compose V3 file format.
-[Learn about Compose files](/compose/compose-file/).
-
-Click **Create** to build and deploy the application. When you see the
-**Created successfully** message, click **Done**.
-
-In the left pane, click **Services** to see the details of the services that
-you deployed across your nodes. Click the `VotingApp_vote` service and find
-the **Published Endpoint** field in the details pane. Click the link to visit
-the voting page, which is published on port `5000`.
-
-![Screenshot of deployed service](../images/deployed_visualizer.png){: .with-border}
-
-Click **Cats** and **Dogs** a few times to register some votes, and notice
-that each click is processed by a different container.
-
-Go back to the **Services** page in the UCP web UI. Click the
-`VotingApp_result` service and find the **Published Endpoint** field in
-the details pane. It has the same URL as the other `VotingApp` services,
-but it's published on port `5001`. Click the link to view the vote tally.
-
-Back in the **Services** page, click the
-`VotingApp_visualizer` service and find the **Published Endpoint** field in
-the details pane. You'll see a link to your UCP instance's URL that includes
-the published port of the visualizer service, which is 8080 in this case.
-
-Visiting this URL accesses the running instance of the `VotingApp_visualizer`
-service in your browser, which shows a map of how this application was deployed:
-
-![Screenshot of visualizer](../images/deployed_visualizer_detail.png){: .with-border}
-
-You can see some of the characteristics of the deployment specification
-from the Compose file in play. For example, the manager node is running the
-PostgreSQL container, as configured by setting `[node.role == manager]` as a
-constraint in the `deploy` key for the `db` service.
-
-## Limitations
-
-There are some limitations when deploying docker-compose.yml applications from
-the UI. You can't reference any external files, so the following Docker
-Compose keywords are not supported:
-
-* build
-* dockerfile
-* env_file
-
-To overcome these limitations, you can
-[deploy your apps from the CLI](deploy-from-cli.md).
-
-Also, UCP doesn't store the compose file used to deploy the application. You can
-use your version control system to persist that file.
-
-{% endif %}

ee/ucp/swarm/deploy-multi-service-app.md

@@ -0,0 +1,166 @@
+---
+title: Deploy a multi-service app
+description: Learn how to deploy containerized applications on a cluster, with Docker Universal Control Plane.
+keywords: ucp, deploy, application, stack, service, compose
+redirect_from:
+  - /ee/ucp/user/services/
+  - /ee/ucp/swarm/deploy-from-cli/
+  - /ee/ucp/swarm/deploy-from-ui/
+ui_tabs:
+- version: ucp-3.0
+  orlower: true
+---
+
+{% if include.version=="ucp-3.0" %}
+
+Docker Universal Control Plane allows you to use the tools you already know,
+like `docker stack deploy` to deploy multi-service applications. You can
+also deploy your applications from the UCP web UI.
+
+In this example we'll deploy a multi-service application that allows users to
+vote on whether they prefer cats or dogs.
+
+```yaml
+version: "3"
+services:
+
+  # A Redis key-value store to serve as message queue
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379"
+    networks:
+      - frontend
+
+  # A PostgreSQL database for persistent storage
+  db:
+    image: postgres:9.4
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    networks:
+      - backend
+
+  # Web UI for voting
+  vote:
+    image: dockersamples/examplevotingapp_vote:before
+    ports:
+      - 5000:80
+    networks:
+      - frontend
+    depends_on:
+      - redis
+
+  # Web UI to count voting results
+  result:
+    image: dockersamples/examplevotingapp_result:before
+    ports:
+      - 5001:80
+    networks:
+      - backend
+    depends_on:
+      - db
+
+  # Worker service to read from message queue
+  worker:
+    image: dockersamples/examplevotingapp_worker
+    networks:
+      - frontend
+      - backend
+
+networks:
+  frontend:
+  backend:
+
+volumes:
+  db-data:
+```
+
+## From the web UI
+
+To deploy your applications from the **UCP web UI**, on the left navigation bar
+expand **Shared resources**, choose **Stacks**, and click **Create stack**.
+
+![Stack list](../images/deploy-multi-service-app-1.png){: .with-border}
+
+Choose the name you want for your stack, and choose **Swarm services** as the
+deployment mode.
+
+When you choose this option, UCP deploys your app using the
+Docker swarm built-in orchestrator. If you choose 'Basic containers' as the
+deployment mode, UCP deploys your app using the classic Swarm orchestrator.
+
+Then copy-paste the application definition in docker-compose.yml format.
+
+![Deploy stack](../images/deploy-multi-service-app-2.png){: .with-border}
+
+Once you're done click **Create** to deploy the stack.
+
+## From the CLI
+
+To deploy the application from the CLI, start by configuring your Docker
+CLI using a [UCP client bundle](../user-access/cli.md).
+
+Then, create a file named `docker-stack.yml` with the content of the yaml above,
+and run:
+
+
+<ul class="nav nav-tabs">
+  <li class="active"><a data-toggle="tab" data-target="#tab1">Swarm orchestrator</a></li>
+  <li><a data-toggle="tab" data-target="#tab2">Classic Swarm orchestrator</a></li>
+</ul>
+<div class="tab-content">
+  <div id="tab1" class="tab-pane fade in active" markdown="1">
+```
+docker stack deploy --compose-file voting_app
+```
+  </div>
+  <div id="tab2" class="tab-pane fade" markdown="1">
+```
+docker-compose --file docker-compose.yml --project-name voting_app up -d
+```
+  </div>
+</div>
+
+
+## Check your app
+
+Once the multi-service application is deployed, it shows up in the UCP web UI.
+The 'Stacks' page shows that you've deployed the voting app.
+
+![Stack deployed](../images/deploy-multi-service-app-3.png){: .with-border}
+
+You can also inspect the individual services of the app you deployed. For that,
+click the **voting_app** to open the details pane, open **Inspect resources** and
+choose **Services**, since this app was deployed with the built-in Docker swarm
+orchestrator.
+
+![Service list](../images/deploy-multi-service-app-4.png){: .with-border}
+
+You can also use the Docker CLI to check the status of your app:
+
+```
+docker stack ps voting_app
+```
+
+Great! The app is deployed so we can cast votes by accessing the service that's
+listening on port 5000.
+You don't need to know the ports a service listens to. You can
+**click the voting_app_vote** service and click on the **Published endpoints**
+link.
+
+![Voting app](../images/deploy-multi-service-app-5.png){: .with-border}
+
+## Limitations
+
+When deploying applications from the web UI, you can't reference any external
+files, no matter if you're using the built-in swarm orchestrator or classic
+Swarm. For that reason, the following keywords are not supported:
+
+* build
+* dockerfile
+* env_file
+
+Also, UCP doesn't store the stack definition you've used to deploy the stack.
+You can use a version control system for this.
+
+{% endif %}

ee/ucp/swarm/index.md

@@ -1,5 +1,5 @@
 ---
-title: Deploy a service
+title: Deploy a single service
 description: Learn how to deploy services to a cluster managed by Universal Control Plane.
 keywords: ucp, deploy, service
 redirect_from:
@@ -65,7 +65,7 @@ You can also deploy the same service from the CLI. Once you've set up your
 
 ```bash
 docker service create --name nginx \
-  --publish 8000:80 \
+  --publish mode=ingress,target=80,published=8000 \
   --label com.docker.ucp.access.owner=<your-username> \
   nginx
 ```