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

diff --git a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst
index d9d9cbe..ed30dd1 100644 (file)
--- 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
 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
 ========================
 
 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.
 
 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
 ==============
 
 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
 ----------------------
 
 
 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:
 
 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.
    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.
 -  **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.
 
    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
 
 
 .. 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
 
 
 .. 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
 
 
 .. 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>
 
     # 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
 ------------------
 
 ONAP Heat Template
 ------------------


@@ -241,47 +232,41 @@ component's containers get spun up).
 Validating APPC Installation
 ============================
 
 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
 ---------------------------
 
 
 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
 
 
 .. code:: bash
 

-    docker exec -it <DOCKER_CONTAINER> bash
+    docker exec -it appc_controller_container bash

 
 Checking if APPC Features are installed successfully
 ----------------------------------------------------
 
 
 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
 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
 
 .. 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
 
     # 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
 
     # 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
 
     # Check reason why bundle failed to load

-    bundle:diag | grep <BUNDLE_NAME>
+    bundle:diag <bundle id>

 
 Accessing the API Explorer
 --------------------------
 
 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.
 
 `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>`__):
 
 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
 ========================
 
 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.
 
 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
 ================
 
 Additional Notes
 ================