docs: restructure build doc

content/docs/using-appsody/building.md

@@ -14,10 +14,7 @@ The [appsody build](/docs/cli-commands/#appsody-build) command completes the fol
 
 - Extracts your code and other artifacts, including a new Dockerfile, which are required to build the *deployment* image from the *development* image. These files are saved to the `~/.appsody/extract` directory.
 - Runs a `docker build` against the Dockerfile that was extracted on the previous step to produce a *deployment* image in your local Docker registry. 
-  - If you want to give the image a name, specify the `-t <tag>` parameter. 
-  - If you want to push the built image to an image repository, specify the `--push` parameter. 
-  - If you run `appsody build` with no parameters, the image is given a name that matches the name of your project.
-- Generates a manifest called `app-deploy.yaml` that can be used to deploy your Appsody application.
+- Generates a deployment manifest file named `app-deploy.yaml` in the project directory, if one doesn’t exist already. If a deployment manifest file exists, this command updates the following entries within it: application image, labels, and annotations.
 
 > If your project includes uppercase characters, these are converted to lowercase characters in the image name because Docker does not accept uppercase characters in image tags. Also, if your project directory includes underscore characters, those will be converted to dashes (-), because certain areas of Kubernetes are not tolerant of underscore characters.
 
@@ -34,4 +31,42 @@ Project extracted to /Users/mchilant/.appsody/extract/appsody-project
 Running command: docker[build -t appsody-project -f /Users/mchilant/.appsody/extract/appsody-project/Dockerfile /Users/mchilant/.appsody/extract/appsody-project]
 Built docker image appsody-project
 Created deployment manifest: /Users/mchilant/appsody-project/app-deploy.yaml
-```
+```
+
+## Tagging your application image
+
+To tag the built application image, use the `-t <tag>` flag along with the `build` command. The tag can be specified in the format `mynamespace/myrepository[:tag]`.
+
+For example:
+```
+appsody build -t <mynamespace/myrepository[:tag]>
+```
+The application image built by `appsody build` will be tagged with the name `mynamespace/myrepository[:tag]`.
+
+> If the `-t` flag is not specified, the image is tagged with the project name.
+
+
+## Pushing your application image to an image registry
+
+### Pushing to Docker Hub
+
+To share your images to the Docker Hub registry, use the `--push` flag along with the `build` command.
+
+For example:
+```
+appsody build -t <mynamespace/myrepository[:tag]> --push 
+```
+The application image built by `appsody build` will be tagged with the name `mynamespace/myrepository[:tag]`, and pushed to the Docker Hub registry.
+
+> If you don't specify the `--push` flag, the image is available only on your local Docker registry. The `--push` flag is also available to the [appsody deploy](/docs/using-appsody/deploying) command.
+
+### Pushing to a custom registry
+By default, the `--push` flag shares your images to the Docker Hub registry. To share your images to a custom registry, use the `--push-url <push-url>` flag along with the `build` command.
+
+For example:
+```
+appsody build -t <mynamespace/myrepository[:tag]> --push-url <registry-url:PORT>
+```
+The application image built by `appsody build` will be tagged with the name `mynamespace/myrepository[:tag]`, and pushed to the registry at the URL that you specify with `<registry-url:PORT>`.
+
+> A push is triggered when using the `--push-url` flag even if the `--push` flag is not specified. The `--push` and `--push-url` flags are also available to the [appsody deploy](/docs/using-appsody/deploying) command.

content/docs/using-appsody/deploying.md

@@ -58,34 +58,26 @@ This command completes the following actions:
 - If you specified the `--knative` flag, or if Knative is the only deployment option for your stack, the command tags the image with the special prefix `dev.local`, making it accessible to your Kubernetes cluster (assuming you followed [these directions](/docs/using-appsody/installing-knative-locally))
 - The deployment manifest, `app-deploy.yaml`, is used to issue a `kubectl apply -f` command against the target Kubernetes cluster so that the application can be deployed by the Appsody Operator.
 
-### Deploying your application through Docker Hub
+### Deploying to a private registry
 
-If your cluster is configured to pull images from Docker Hub, use the following command to deploy your application:
+If you are pulling your image from a registry within your cluster, the registry may only be accessed by using a different name from outside your cluster, and a different name from within your cluster. For example, you might want to push to an external registry and pull from an internal registry.
+
+To specify different push and pull registries, use the following command:
 ```
-appsody deploy -t <mynamespace/myrepository[:tag]> --push --namespace mynamespace [--knative]
+appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <external-registry-url:PORT> --pull-url <internal-registry-url:PORT>
 ```
-The command completes the following actions:
 
-- Calls `appsody build` and creates a deployment image, as described in the previous section.
-- The `-t mynamespace/myrepository[:tag]` flag tags the image.
-- The `--push` flag tells the Appsody CLI to push the image to Docker Hub.
-- Creates a deployment manifest file named `app-deploy.yaml` in the project directory, if one doesn’t exist already. If a deployment manifest file exists, this command updates the following entries within it: application image, labels, and annotations. In addition, the `createKnativeService` entry is set to true if you specified the `--knative` flag.
-- The Yaml file is used to issue a `kubectl apply -f` command against the target Kubernetes cluster. The Yaml file is set to use the Appsody operator.
-- The `--namespace mynamespace` option provisions the deployment under the specified Kubernetes namespace within your cluster.
+This command completes the following actions:
 
-> If you don't specify `--push`, the image is available only on your local Docker registry and the target Kubernetes cluster must be configured to have access to your local Docker registry.
+- Calls `appsody build` and creates a deployment image.
+- The `-t mynamespace/myrepository[:tag]` flag tags the image.
+- The `--push-url` pushes the image to `<external-registry-url:PORT>`.
+- Generates a deployment manifest file, "app-deploy.yaml", if one is not present, then applies it to your Kubernetes cluster.
+- The `--pull-url` injects `<internal-registry-url:PORT>` into the deployment manifest for Kubernetes to pull the correct image.
+- Deploys your image to your Kubernetes cluster via the [Appsody operator](/docs/reference/appsody-operator), or as a Knative service if you specify the "--knative" flag. 
 
-### Deploying your application to a custom registry
-If your cluster is configured to pull images from a custom registry, use the following command to deploy your application:
-```
-appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <registry-url:PORT>
-```
+> If an [Appsody operator](/docs/reference/appsody-operator) cannot be found, one will be installed on your cluster.
 
-If you are specifying different push and pull registries, for example, you might want to push to an external registry and pull from an internal registry, use the following command:
-```
-appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <external-registry-url:PORT> --pull-url <internal-registry-url:PORT>
-```
-> Note: The pull registry url gets injected into the deployment manifest for Kubernetes to pull the correct image.
 
 ### Deploying multiple projects
 If you are running multiple Appsody projects on your workstation, you can use `appsody deploy` and `appsody operator` commands to get them deployed to a Kubernetes cluster. However, make sure that you run these commands one at a time, because those commands create temporary files that might lead to conflicts if created concurrently.