Docs: Update to deployment guidelines

Updating the deployment guidelines document so that
it matches the current deployment process.

Change-Id: I9e8edb38046c6e5f9e9e9a342c6edd962a4047bd
Signed-off-by: Patrick Brady <patrick.brady@att.com>
Issue-ID: APPC-1863

1 files changed, 131 insertions, 159 deletions

diff --git a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst
index d9d9cbe..ed30dd1 100644
--- a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst
+++ b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst
@@ -33,7 +33,7 @@ as well as enabling automation and a dynamic configuration approach.
 ONAP APPC is delivered either as as a Kubernetes based Cloud Native
 deployment or as an OpenStack deployment with **4 Docker Containers**,
 which are deployed using Docker Images already containing the APPC
-Framework Suite. NOTE: Containers are hosted on Ubuntu 16.04 LTS OS.
+Framework Suite.
 
 Deployment Mode for APPC
 ========================
@@ -42,33 +42,24 @@ The docker containers described above are set up to be deployed on the
 same Virtual Machine. **Docker Compose** is Docker's deployment tool
 that allows to configure and deploy multiple containers at once.
 
-Compiling and Building APPC
-===========================
-
-APPC (structured as a Maven project) uses the Maven tool to help
-compile, build, and deploy APPC Artifacts (usually made up of Java
-packages) into a Maven Repository. In order to compile and build APPC, a
-``mvn clean install`` is executed, which checks for any errors and Java
-exceptions during compilation process.
-
 Deploying APPC
 ==============
 
-In order to deploy APPC, a Docker-ready machine needs to be available in
-order to deploy the APPC Docker Containers. The following will help
-explain the requirements in order to run Docker to deploy these
-containers.
+Appc runs on a series of Docker containers. In production, these Docker
+containers are run as part of a Kubernetes cluster using Helm charts,
+but the Docker containers can be brought up without using Kubernetes
+(using docker-compose), for the purposes of testing.
 
 APPC Docker Containers
 ----------------------
 
-ONAP APPC docker images are currently stored on the Rackspace Nexus
-Docker Registry (Maven Repository). The deployment code can be found in
-the Maven Project that builds and deploys the Docker Images to be
-deployed in the Nexus Repository (current approach is by using Jenkins).
-These Docker Images are composed of the APPC Artifacts
-(org.onap.appc.\*) compiled and packaged in the "appc" git
-repository.
+Pre-built ONAP APPC docker images are stored on the LF Nexus 3 server
+(nexus3.onap.org). Snapshot docker images contain snapshot versions of
+appc components. They are updated daily. These can be found in the
+snapshots repository on Nexus 3. The release docker images contain only
+released versions of appc components, and once a release docker image is
+created, it will not change. These can be found in the releases repository
+of Nexus 3.
 
 The following Docker images are the actual deployment images used for
 running APPC:
@@ -81,6 +72,9 @@ running APPC:
    Active & Available Inventory (A&AI) Listener). Some of these
    inherited SDN-C features/artifacts are necessary dependencies to
    build and compile APPC features/artifacts.
+-  **APPC CDT Container**: This docker container hosts the CDT front-end
+   gui using nodejs. The artifacts that are contained in this docker container
+   come from the appc/cdt repository.
 -  **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
    It’s made by the original developers of MySQL and guaranteed to stay 
    open source.
@@ -91,142 +85,139 @@ running APPC:
    Virtual Functions. NOTE: This container is deployed using a Docker
    Image that is managed and supported by the SDN-C component.
 
-Starting APPC
-=============
+Running APPC Containers
+=======================
 
-Ther following steps are needed to deploy and start ONAP APPC:
+The following steps are needed to deploy and start ONAP APPC:
 
-Requirement to Pre-Define properties before compiling APPC:
------------------------------------------------------------
+Preparing your Docker environment
+---------------------------------
 
--  The following maven properties are not defined by default, since they
-   change based on where the platform is being deployed:
+-  The VM where APPC will be started needs to have Docker Engine and
+   Docker-Compose installed (instructions on how to set Docker Engine
+   can be found
+   `here <https://docs.docker.com/engine/installation/>`__).
+   
+-  The Nexus repository certificate must be added to the
+   /usr/local/share/ca-certificates/ path
+   
+-  You must login to the Nexus repository using this command:
+
+   .. code:: bash
+   
+       docker login nexus3.onap.org:10001
+
+Downloading the Docker Compose File
+----------------------------------
 
-   -  ${openecomp.nexus.url}: URL of the Nexus Repository where APPC
-      Code is at.
-   -  ${openecomp.nexus.port}: Port number of the Nexus Repository where
-      APPC Code is at.
-   -  ${openecomp.nexus.user}: Username ID of the Nexus Repository where
-      APPC Code is at.
-   -  ${openecomp.nexus.password}: Password of the Nexus Repository
-      where APPC Code is at.
+The docker-compose file is needed to setup and start the docker containers.
+This file, "docker-compose.yml", is located in the "docker-compose"
+directory of the appc/deployment repository.
 
-Using Jenkins Jobs to set up APPC Package
------------------------------------------
+You can clone this repository to your docker host:
 
--  A Jenkins instance for ONAP is required, in which Jenkins Jobs for
-   both the APPC core code and deployment code are maintained.
+.. code:: bash
 
--  Jenkins Job for APPC Core git project: The Jenkins Job for the APPC
-   git repository (Core Component) is in charge of compiling and
-   uploading/deploying successfully compiled maven APPC artifacts into a
-   Nexus/Maven Repository.
+    git clone "https://gerrit.onap.org/r/appc/deployment"
 
--  Jenkins Job for APPC Deployment git project: The Jenkins Job is used
-   to run the APPC Deployment code which ultimately builds and deploy
-   the APPC Docker Image. Once the Jenkins job runs successfully, the
-   newly compiled images are uploaded to the Nexus Repository. The APPC
-   Docker image contains all the SDN-C and APPC artifacts needed to
-   deploy a successful APPC Component.
+Downloading the APPC Docker Images
+----------------------------------
 
-   -  With this job, all required and newly compiled and uploaded (to
-      Nexus Repository) APPC features from the Jenkins job are pulled
-      into the images and installed in an automated fashion.
+Several images need to be dowloaded from nexus for the full appc install:
+appc-image, appc-cdt-image, ccsdk-dgbuilder-image, and ccsdk-ansible-server-image.
 
--  As explained in the "APPC Docker Containers" section, the
-   configuration and set up of the other two docker containers are not
-   maintained by APPC. MySQL Docker Image is maintained by the Open
-   Source MySQL Community and the Node Red / DGBuilder Docker Image is
-   maintained by SDN-C.
+The command to pull an image is:
 
-Using Docker to start APPC Package
-----------------------------------
+.. code:: bash
 
--  The VM where APPC will be started needs to have Docker Engine and
-   Docker-Compose installed (instructions on how to set Docker Engine
-   can be found
-   `here <https://docs.docker.com/engine/installation/>`__). The stable
-   version of Docker Engine where APPC has been tested to work is v1.12.
-   An important requirement in order to access the Docker Image
-   Repository on Nexus Repository (where docker images are currently
-   stored) need to include the Nexus repository certificate imported in
-   the host VM. This is needed for Docker to be able to access the
-   Docker Images required (NOTE: MySQL Docker Image is obtained from the
-   public Docker Hub).
-
--  NOTE ON "docker-compose" COMMANDS: The only work if there is a
-   provided docker-compose YAML script in the cmd path
-
--  In order to deploy containers, the following steps need to be taken
-   in your host VM (Assuming instructions on how to set up Docker Engine
-   have already been done):
+    docker pull nexus3.onap.org:10001/onap/<image name>:<image version>
+    
+    You can find the versions of the images that you want to download in Nexus,
+    then download them with the above command.
+
+Re-Tagging the Docker Images
+----------------------------
+
+The docker images that you downloaded from nexus will need to be re-tagged to match
+the image names that the docker-compose file is looking for. If you open the
+docker-compose.yml file, you'll see the image names, for example "onap/appc-image:latest".
+
+First, check the list of images you have downloaded:
 
 .. code:: bash
 
-    # Install Docker-Compose
-    apt-get install python-pip
-    pip install docker-compose
+    docker images
 
-    # Login to Nexus Repo to pull Docker Images (this assumes that Nexus Certificate is already imported in the Host VM on /usr/local/share/ca-certificates/ path):
-    docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
+Find the version of the image you want to tag in the output and note the image id. Run this command to tag
+that image. In this example, we are tagging a version of the "appc-image".
 
-    # Pull latest version of Docker Images (separately)
-    docker pull <APPC_DOCKER_IMAGE_URL>
-    docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
-    docker pull <SDNC_DOCKER_IMAGE_URL>
+.. code:: bash
 
-    # Pull latest version of Docker Images
-    docker-compose pull
+    docker tag <image-id> onap/appc-image:latest
 
-    # Deploy Containers
-    docker-compose up  # add -d argument to start process as a daemon (background process)
+Repeat this process for the other images in the docker-compose file that you want to bring up.
 
-Using Docker to stop APPC Package
----------------------------------
+Starting the Docker Containers
+------------------------------
+
+In order to run docker-compose commands, you need to be in the same directory that your
+docker-compose.yml is located in.
+
+In order to create and start the appc Docker containers, run this command:
 
--  The following steps are required to stop the APPC package:
+.. code:: bash
+
+    docker-compose up -d
+
+You can see the status of all Docker containers on your host with this:
 
 .. code:: bash
 
-    # Stop and Destroy Docker Containers (with docker-compose YAML script)
-    docker-compose down
+    docker ps -a
 
-    # Stop Docker Containers (without docker-compose YAML script)
-    docker stop <APPC_DOCKER_CONTAINER>
-    docker stop <MYSQL_DOCKER_CONTAINER>
-    docker stop <DGBUILDER_DOCKER_CONTAINER>
+You can check the progress of the appc container start-up by viewing the Docker logs:
 
-    # Destroy Docker Containers (without docker-compose YAML script)
-    docker rm <APPC_DOCKER_CONTAINER>
-    docker rm <MYSQL_DOCKER_CONTAINER>
-    docker rm <DGBUILDER_DOCKER_CONTAINER>
+.. code:: bash
 
--  NOTE: To get a feel of how the deployment is actually performed, it
-   is best to review the Docker Strategy of APPC and look at the actual
-   Jenkins Jobs.
+    docker-compose logs
 
-Other Useful Docker Commands
-----------------------------
+When you see "Total Appc install took:" in the log, the appc install has finished.
+
+Stopping the Docker Containers
+------------------------------
 
--  The commands below are useful to test or troubleshoot in case a
-   change in the gitlab code breaks a clean APPC deployment:
+A Docker container can be stopped with this command:
 
 .. code:: bash
 
-    # Check current docker-compose logs generated during 'docker-compose up' process:
-    docker-compose logs # add -f to display logs in real time
+    docker stop <container name or id>
+
+The container can be deleted with this command:
+
+.. code:: bash
+
+    docker rm -v <container name or id>
+
+(make sure you use the -v parameter or the volume will not be removed)
+
+
+Other Useful Docker Management Commands
+---------------------------------------
+
+.. code:: bash
 
     # Check out docker container's current details
     docker inspect <DOCKER_CONTAINER>
 
     # Verbose output during docker-compose commands
     docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
+    
+    #Stop all running docker containers
+    docker ps | while read a b c d e f g; do docker stop $a; done
+    
+    #Remove all docker containers (but not the images you have downloaded)
+    docker ps -a | while read a b c d e f g; do docker rm -v $a; done
 
-    # Check previous docker volumes
-    docker volume ls
-
-    # Delete previous docker volume(s)
-    docker volume rm <DOCKER_VOL_ID_1> <DOCKER_VOL_ID_2> ... <DOCKER_VOL_ID_N>
 
 ONAP Heat Template
 ------------------
@@ -241,47 +232,41 @@ component's containers get spun up).
 Validating APPC Installation
 ============================
 
-First of all, APPC Features come in the form of Karaf Features (an
-ODL-OpenDaylight package) which can be composed of one or more OSGI
-bundles. These features get installed in the ODL framework in order to
-be used and installed in the APPC Docker Container (NOTE: SDN-C Core
-Features also get installed since APPC docker image uses the SDN-C Core
-docker image as a base image).
+The Appc application runs as a series of OSGI features and bundles in Opendaylight on the
+Appc docker container. You can confirm that Appc installed by making sure these features
+show up in the Opendaylight console.
 
 Accessing docker containers
 ---------------------------
 
-The following command is used to log in / access the docker containers:
+The following command is used to log in / access the Appc Docker container and start a shell session:
 
 .. code:: bash
 
-    docker exec -it <DOCKER_CONTAINER> bash
+    docker exec -it appc_controller_container bash
 
 Checking if APPC Features are installed successfully
 ----------------------------------------------------
 
-The following commands are used to check if the APPC (and SDN-C) Bundles
+The following commands are used to check if the APPC Bundles
 and Features have been installed correctly in ODL (make sure to enter
-the APPC Docker Container shell session):
+the APPC Docker Container shell session first):
 
 .. code:: bash
 
     # All commands are done inside the appc docker container
 
     # Enter the ODL Karaf Console
-    cd /opt/opendaylight/current/bin
-    ./client -u karaf
+    /opt/opendaylight/current/bin/client
 
     # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
     feature:list | grep appc # filter appc features only
-    feature:list | grep sdnc # filter sdn-c features only
 
     # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
     bundle:list | grep appc # filter appc bundles only
-    bundle:list | grep sdnc # grep sdn-c bundles only
 
     # Check reason why bundle failed to load
-    bundle:diag | grep <BUNDLE_NAME>
+    bundle:diag <bundle id>
 
 Accessing the API Explorer
 --------------------------
@@ -293,18 +278,13 @@ REST calls, some APIs use the
 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
 make such calls.
 
-Currently, the APIs that have a Directed Graph (DG) mapped to it are the
-ones that can be tested which are the SDN-C APIs and APPC
-"appc-provider" APIs (LCM APIs will be available to test in later
-releases).
-
 In order to access this GUI, you need to go to the following website
 which will prompt for ODL user credentials in order to authenticate
 (more details on generic API Explorer
 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
 
--  http://localhost:8282/apidoc/explorer/index.html (change localhost to
-   your VM's public IP).
+-  http://localhost:8282/apidoc/explorer/index.html (localhost can be replaced with the ip of your
+   Docker host, if it is not on localhost).
 
 APPC Configuration Model
 ========================
@@ -327,25 +307,17 @@ feature need to be defined to point to the right DMaaP set of events to
 make sure that we are sending and receiving the proper messages on
 DMaaP.
 
-Currently, there are two ways to change properties for APPC Features:
-
--  **Permanent Change**: In appc.properties, change property values as
-   needed and commit changes in your current git repo where your APPC
-   Deployment code repo is at. Then, run your Jenkins job that deploys
-   the APPC Docker Image (make sure the Jenkins Job configuration points
-   to the branch where you just commited the properties change) to make
-   sure that APPC Docker Image contains latest changes of
-   appc.properties from the beginning (of course, the Host VM where the
-   docker containers will be deployed at needs to update images with
-   "docker-compose pull" to pick up the changes you just committed and
-   compiled).
--  **Temporary Change (for quick testing/debugging)**: In the APPC
-   Docker Container, find the appc.properties file in
-   /opt/onap/appc/properties/appc.properties and make changes as
-   needed. Then, restart the APPC Docker Container by running "docker
-   stop " then "docker start ") (NOTE: This approach will lose all
-   changes done in appc.properties if the docker container is destroyed
-   instead of stopped).
+Temporary changes to the appc.properties file can be made by entering the Appc
+Docker container and modifying the /opt/onap/appc/properties/appc.properties file.
+Then, from outside the Docker container, you should stop and then restart the Appc
+Docker container with these commands:
+
+.. code:: bash
+
+    docker stop appc_controller_container
+
+    docker stop appc_controller_container
+
 
 Additional Notes
 ================