-# OpenECOMP APP-C
+# ONAP APPC
---
---
# Introduction
-The Application Controller (APP-C) is one of the components in the OpenECOMP Platform. Its main function is to perform functions to control the lifecycle of Virtual Functions (VNFs) as well as the components that make up these functions. Therefore, this allows the cloud to be abstracted from Virtual Functions in order to enable repeatable actions, as well as enabling automation and a dynamic configuration approach.
+The Application Controller (APPC) is one of the components in the ONAP Platform. Its main function is to perform functions to control the lifecycle of Virtual Functions (VNFs) as well as the components that make up these functions. Therefore, this allows the cloud to be abstracted from Virtual Functions in order to enable repeatable actions, as well as enabling automation and a dynamic configuration approach.
-OpenECOMP APP-C is delivered with **3 Docker Containers**, which are deployed using Docker Images already containing the APP-C Framework Suite.
+ONAP APPC is delivered with **3 Docker Containers**, which are deployed using Docker Images already containing the APPC Framework Suite.
NOTE: All three containers are hosted on Ubuntu 14.04 LTS OS.
-# Deployment Mode for APP-C
+# Deployment Mode for APPC
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 APP-C
+# Compiling and Building APPC
-APP-C (structured as a Maven project) uses the Maven tool to help compile, build, and deploy APP-C Artifacts (usually made up of Java packages) into a Maven Repository. In order to compile and build APP-C, a `mvn clean install` is executed, which checks for any errors and Java exceptions during compilation process.
+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 APP-C
-In order to deploy APP-C, a Docker-ready machine needs to be available in order to deploy the APP-C Docker Containers. The following will help explain the requirements in order to run Docker to deploy these containers.
+# 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.
-### APP-C Docker Containers
-OpenECOMP APP-C 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 APP-C Artifacts (org.openecomp.appc.*) compiled and packaged in the "appc" git repository.
+### 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.openecomp.appc.*) compiled and packaged in the "appc" git repository.
-The following Docker images are the actual deployment images used for running APP-C:
-- **APP-C Container (Version 1.0.0)**: This Docker container carries the APP-C Core Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and APP-C specific features). This image is built on top of the SDN-C Docker Image, which contains core features (such as dblib as the Database Connector, SLI - the Service Logic Interpreter, and the Active & Available Inventory (A&AI) Listener). Some of these inherited SDN-C features/artifacts are necessary dependencies to build and compile APP-C features/artifacts.
-- **MySQL DB Container (Version 5.6)**: This is the database for APP-C. It is currently using MySQL Community Version (Open-Source version).
-- **Node Red / DGBuilder (Version 1.0.0)**: This container has the visual tool used to assemble DGs in order to put together flows or services used to serve Virtual Functions. NOTE: This container is deployed using a Docker Image that is managed and supported by the SDN-C component.
+The following Docker images are the actual deployment images used for running APPC:
+- **APPC Container**: This Docker container carries the APPC Core Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and APPC specific features). This image is built on top of the SDN-C Docker Image, which contains core features (such as dblib as the Database Connector, SLI - the Service Logic Interpreter, and the Active & Available Inventory (A&AI) Listener). Some of these inherited SDN-C features/artifacts are necessary dependencies to build and compile APPC features/artifacts.
+- **MySQL DB Container (Version 5.6)**: This is the database for APPC. It is currently using MySQL Community Version (Open-Source version).
+- **Node Red / DGBuilder**: This container has the visual tool used to assemble DGs in order to put together flows or services used to serve Virtual Functions. NOTE: This container is deployed using a Docker Image that is managed and supported by the SDN-C component.
-# Starting APP-C
+# Starting APPC
-Ther following steps are needed to deploy and start OpenECOMP APP-C:
+Ther following steps are needed to deploy and start ONAP APPC:
-##### Requirement to Pre-Define properties before compiling APP-C:
+##### Requirement to Pre-Define properties before compiling APPC:
- The following maven properties are not defined by default, since they change based on where the platform is being deployed:
- - ${ecomp.nexus.url}: URL of the Nexus Repository where APP-C Code is at.
- - ${ecomp.nexus.port}: Port number of the Nexus Repository where APP-C Code is at.
- - ${ecomp.nexus.user}: Username ID of the Nexus Repository where APP-C Code is at.
- - ${ecomp.nexus.password}: Password of the Nexus Repository where APP-C Code is at.
+ - ${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.
-##### Using Jenkins Jobs to set up APP-C Package
-- A Jenkins instance for OpenECOMP is required, in which Jenkins Jobs for both the APP-C core code and deployment code are maintained.
+##### Using Jenkins Jobs to set up APPC Package
+- A Jenkins instance for ONAP is required, in which Jenkins Jobs for both the APPC core code and deployment code are maintained.
-- Jenkins Job for APP-C Core git project: The Jenkins Job for the APP-C git repository (Core Component) is in charge of compiling and uploading/deploying successfully compiled maven APP-C artifacts into a Nexus/Maven Repository.
+- 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.
-- Jenkins Job for APP-C Deployment git project: The Jenkins Job is used to run the APP-C Deployment code which ultimately builds and deploy the APP-C Docker Image. Once the Jenkins job runs successfully, the newly compiled images are uploaded to the Nexus Repository. The APP-C Docker image contains all the SDN-C and APP-C artifacts needed to deploy a successful APP-C Component.
- - With this job, all required and newly compiled and uploaded (to Nexus Repository) APP-C features from the Jenkins job are pulled into the images and installed in an automated fashion.
+- 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.
+ - 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.
-- As explained in the "APP-C Docker Containers" section, the configuration and set up of the other two docker containers are not maintained by APP-C. MySQL Docker Image is maintained by the Open Source MySQL Community and the Node Red / DGBuilder Docker Image is maintained by SDN-C.
+- 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.
-##### Using Docker to start APP-C Package
+##### Using Docker to start APPC Package
-- The VM where APP-C 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 APP-C 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).
+- 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
docker-compose up # add -d argument to start process as a daemon (background process)
```
-##### Using Docker to stop APP-C Package
+##### Using Docker to stop APPC Package
-- The following steps are required to stop the APP-C package:
+- The following steps are required to stop the APPC package:
```bash
# Stop and Destroy Docker Containers (with docker-compose YAML script)
docker rm <DGBUILDER_DOCKER_CONTAINER>
```
-- NOTE: To get a feel of how the deployment is actually performed, it is best to review the Docker Strategy of APP-C and look at the actual Jenkins Jobs.
+- 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.
#### Other Useful Docker Commands
-- The commands below are useful to test or troubleshoot in case a change in the gitlab code breaks a clean APP-C deployment:
+- The commands below are useful to test or troubleshoot in case a change in the gitlab code breaks a clean APPC deployment:
```bash
# Check current docker-compose logs generated during 'docker-compose up' process:
# Verbose output during docker-compose commands
docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
+
+# 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>
```
-## OpenECOMP Heat Template
+## ONAP Heat Template
-A Heat template that can be used on RackSpace to spin up the APP-C Host VM as well as the other OpenECOMP Components is available in gitlab. This template would orchestrate the deployment of all OpenECOMP components, which will trigger docker instantiation techniques to start up the containers (either standard docker or docker-compose - depending on how the component's containers get spun up).
+A Heat template that can be used on RackSpace to spin up the APPC Host VM as well as the other ONAP Components is available in gitlab. This template would orchestrate the deployment of all ONAP components, which will trigger docker instantiation techniques to start up the containers (either standard docker or docker-compose - depending on how the component's containers get spun up).
-# Validating APP-C Installation
+# Validating APPC Installation
-First of all, APP-C 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 APP-C Docker Container (NOTE: SDN-C Core Features also get installed since APP-C docker image uses the SDN-C Core docker image as a base image).
+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).
### Accessing docker containers
docker exec -it <DOCKER_CONTAINER> bash
```
-### Checking if APP-C Features are installed successfully
+### Checking if APPC Features are installed successfully
-The following commands are used to check if the APP-C (and SDN-C) Bundles and Features have been installed correctly in ODL (make sure to enter the APP-C Docker Container shell session):
+The following commands are used to check if the APPC (and SDN-C) Bundles and Features have been installed correctly in ODL (make sure to enter the APPC Docker Container shell session):
```bash
# All commands are done inside the appc docker container
./client -u karaf
# 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 app-c features only
+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 app-c bundles only
+bundle:list | grep appc # filter appc bundles only
bundle:list | grep sdnc # grep sdn-c bundles only
# Check reason why bundle failed to load
```
### Accessing the API Explorer
-The API Explorer is a GUI provided by OpenDaylight Open Source Framework. This GUI is very useful to send API calls from APIs that are either developed by APP-C or SDN-C frameworks. In order to make these REST calls, some APIs use the [RESTCONF](http://sdntutorials.com/what-is-restconf/) protocol to make such calls.
+The API Explorer is a GUI provided by OpenDaylight Open Source Framework. This GUI is very useful to send API calls from APIs that are either developed by APPC or SDN-C frameworks. In order to make these 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 APP-C "appc-provider" APIs (LCM APIs will be available to test in later releases).
+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).
-# APP-C Configuration Model
+# APPC Configuration Model
-APP-C Configuration model involves using "default.properties" files (which are usually located in each of the APP-C Features - ../<APPC_FEATURE_BUNDLE>/src/<MAIN_OR_TEST>/resources/org/openecomp/appc/default.properties) for APP-C Feature that have default (or null) property values inside the core APP-C code. These default (or null) properties should be overwritten in the properties file called "appc.properties" located in the APP-C Deployment code (../installation/src/main/appc-properties/appc.properties).
+APPC Configuration model involves using "default.properties" files (which are usually located in each of the APPC Features - ../<APPC_FEATURE_BUNDLE>/src/<MAIN_OR_TEST>/resources/org/openecomp/appc/default.properties) for APPC Feature that have default (or null) property values inside the core APPC code. These default (or null) properties should be overwritten in the properties file called "appc.properties" located in the APPC Deployment code (../installation/src/main/appc-properties/appc.properties).
-Each APP-C component depends on the property values that are defined for them in order to function properly. For example, the APP-C Feature "appc-rest-adapter" located in the APP-C Core repo is used to listen to events that are being sent and received in the form of DMaaP Messages through a DMaaP Server Instance (which is usually defined as a RESTful API Layer over the Apache Kafka Framework). The properties for this 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.
+Each APPC component depends on the property values that are defined for them in order to function properly. For example, the APPC Feature "appc-rest-adapter" located in the APPC Core repo is used to listen to events that are being sent and received in the form of DMaaP Messages through a DMaaP Server Instance (which is usually defined as a RESTful API Layer over the Apache Kafka Framework). The properties for this 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 APP-C Features:
-- Permanent Change: In appc.properties, change property values as needed and commit changes in your current git repo where your APP-C Deployment code repo is at. Then, run your Jenkins job that deploys the APP-C Docker Image (make sure the Jenkins Job configuration points to the branch where you just commited the properties change) to make sure that APP-C 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 APP
-C Docker Container, find the appc.properties file in /opt/openecomp/appc/properties/appc.properties and make changes as needed. Then, restart the APP-C Docker Container by running "docker stop <APPC_DOCKER_CONTAINER>" then "docker start <APPC_DOCKER_CONTAINER>") (NOTE: This approach will lose all changes done in appc.properties if the docker container is destroyed instead of stopped).
+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 APP
C Docker Container, find the appc.properties file in /opt/openecomp/appc/properties/appc.properties and make changes as needed. Then, restart the APPC Docker Container by running "docker stop <APPC_DOCKER_CONTAINER>" then "docker start <APPC_DOCKER_CONTAINER>") (NOTE: This approach will lose all changes done in appc.properties if the docker container is destroyed instead of stopped).
# Additional Notes
-- For more information on a current list of available properties for APP-C Features, please go to README.md located in the installation directory path of the APP-C Deployment Code.
+- For more information on a current list of available properties for APPC Features, please go to README.md located in the installation directory path of the APPC Deployment Code.
+- More documentation can be found on the ONAP Wiki's [APPC Documentation Page](https://wiki.onap.org/display/DW/Controllers) and in ONAP's [Read the docs](http://onap.readthedocs.io/en/latest/release/index.html#projects) documentation site.
--- /dev/null
+==========================
+APPC Deployment Guidelines
+==========================
+
+Introduction
+============
+
+The Application Controller (APPC) is one of the components in the ONAP
+Platform. Its main function is to perform functions to control the
+lifecycle of Virtual Functions (VNFs) as well as the components that
+make up these functions. Therefore, this allows the cloud to be
+abstracted from Virtual Functions in order to enable repeatable actions,
+as well as enabling automation and a dynamic configuration approach.
+
+ONAP APPC is delivered with **3 Docker Containers**, which are deployed
+using Docker Images already containing the APPC Framework Suite. NOTE:
+All three containers are hosted on Ubuntu 14.04 LTS OS.
+
+Deployment Mode for APPC
+========================
+
+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 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.openecomp.appc.\*) compiled and packaged in the "appc" git
+repository.
+
+The following Docker images are the actual deployment images used for
+running APPC:
+
+- **APPC Container**: This Docker container carries the APPC Core
+ Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and
+ APPC specific features). This image is built on top of the SDN-C
+ Docker Image, which contains core features (such as dblib as the
+ Database Connector, SLI - the Service Logic Interpreter, and the
+ Active & Available Inventory (A&AI) Listener). Some of these
+ inherited SDN-C features/artifacts are necessary dependencies to
+ build and compile APPC features/artifacts.
+- **MySQL DB Container (Version 5.6)**: This is the database for APPC.
+ It is currently using MySQL Community Version (Open-Source version).
+- **Node Red / DGBuilder**: This container has the visual tool used to
+ assemble DGs in order to put together flows or services used to serve
+ Virtual Functions. NOTE: This container is deployed using a Docker
+ Image that is managed and supported by the SDN-C component.
+
+Starting APPC
+=============
+
+Ther following steps are needed to deploy and start ONAP APPC:
+
+Requirement to Pre-Define properties before compiling APPC:
+-----------------------------------------------------------
+
+- The following maven properties are not defined by default, since they
+ change based on where the platform is being deployed:
+
+ - ${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.
+
+Using Jenkins Jobs to set up APPC Package
+-----------------------------------------
+
+- A Jenkins instance for ONAP is required, in which Jenkins Jobs for
+ both the APPC core code and deployment code are maintained.
+
+- 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.
+
+- 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.
+
+ - 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.
+
+- 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.
+
+Using Docker to start APPC Package
+----------------------------------
+
+- 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):
+
+.. code:: bash
+
+ # Install Docker-Compose
+ apt-get install python-pip
+ pip install docker-compose
+
+ # 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
+
+ # 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>
+
+ # Pull latest version of Docker Images
+ docker-compose pull
+
+ # Deploy Containers
+ docker-compose up # add -d argument to start process as a daemon (background process)
+
+Using Docker to stop APPC Package
+---------------------------------
+
+- The following steps are required to stop the APPC package:
+
+.. code:: bash
+
+ # Stop and Destroy Docker Containers (with docker-compose YAML script)
+ docker-compose down
+
+ # Stop Docker Containers (without docker-compose YAML script)
+ docker stop <APPC_DOCKER_CONTAINER>
+ docker stop <MYSQL_DOCKER_CONTAINER>
+ docker stop <DGBUILDER_DOCKER_CONTAINER>
+
+ # Destroy Docker Containers (without docker-compose YAML script)
+ docker rm <APPC_DOCKER_CONTAINER>
+ docker rm <MYSQL_DOCKER_CONTAINER>
+ docker rm <DGBUILDER_DOCKER_CONTAINER>
+
+- 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.
+
+Other Useful Docker Commands
+----------------------------
+
+- The commands below are useful to test or troubleshoot in case a
+ change in the gitlab code breaks a clean APPC deployment:
+
+.. code:: bash
+
+ # Check current docker-compose logs generated during 'docker-compose up' process:
+ docker-compose logs # add -f to display logs in real time
+
+ # 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 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
+------------------
+
+A Heat template that can be used on RackSpace to spin up the APPC Host
+VM as well as the other ONAP Components is available in gitlab. This
+template would orchestrate the deployment of all ONAP components, which
+will trigger docker instantiation techniques to start up the containers
+(either standard docker or docker-compose - depending on how the
+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).
+
+Accessing docker containers
+---------------------------
+
+The following command is used to log in / access the docker containers:
+
+.. code:: bash
+
+ docker exec -it <DOCKER_CONTAINER> bash
+
+Checking if APPC Features are installed successfully
+----------------------------------------------------
+
+The following commands are used to check if the APPC (and SDN-C) Bundles
+and Features have been installed correctly in ODL (make sure to enter
+the APPC Docker Container shell session):
+
+.. code:: bash
+
+ # All commands are done inside the appc docker container
+
+ # Enter the ODL Karaf Console
+ cd /opt/opendaylight/current/bin
+ ./client -u karaf
+
+ # 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>
+
+Accessing the API Explorer
+--------------------------
+
+The API Explorer is a GUI provided by OpenDaylight Open Source
+Framework. This GUI is very useful to send API calls from APIs that are
+either developed by APPC or SDN-C frameworks. In order to make these
+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).
+
+APPC Configuration Model
+========================
+
+APPC Configuration model involves using "default.properties" files
+(which are usually located in each of the APPC Features -
+..//src//resources/org/openecomp/appc/default.properties) for APPC
+Feature that have default (or null) property values inside the core APPC
+code. These default (or null) properties should be overwritten in the
+properties file called "appc.properties" located in the APPC Deployment
+code (../installation/src/main/appc-properties/appc.properties).
+
+Each APPC component depends on the property values that are defined for
+them in order to function properly. For example, the APPC Feature
+"appc-rest-adapter" located in the APPC Core repo is used to listen to
+events that are being sent and received in the form of DMaaP Messages
+through a DMaaP Server Instance (which is usually defined as a RESTful
+API Layer over the Apache Kafka Framework). The properties for this
+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/openecomp/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).
+
+Additional Notes
+================
+
+- For more information on a current list of available properties for
+ APPC Features, please go to README.md located in the installation
+ directory path of the APPC Deployment Code.
+- More documentation can be found on the ONAP Wiki's `APPC
+ Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
+ and in ONAP's `Read the
+ docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__
+ documentation site.
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+=================================
+Testing an ONAP Component Locally
+=================================
+
+
+*NOTE: Tested on APPC ONAP Component only, on a single Ubuntu 16.04 LTS
+VM*
+
+See also `Developing
+ONAP <https://wiki.onap.org/display/DW/Developing+ONAP>`__
+
+
+General Requirements
+====================
+
+- A Gerrit Account – to create a Gerrit account, please create one
+ here: https://identity.linuxfoundation.org
+
+|image0|
+
+- An Ubuntu 16.04 LTS Desktop VM (14.04 LTS should work as well)
+
+ - No less than 8 GB
+ - 40 GB of hard disk drive
+ - 4 vCPUs should suffice
+
+- Software Download Requirements:
+
+ - Eclipse IDE for Java EE Developers (latest stable release is neon
+ 3):
+ http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/neon3
+ - Nexus OSS 2 (to upload ONAP Component’s Maven Artifacts locally):
+ https://www.sonatype.com/download-oss-sonatype - grab the
+ bundle.tar.gz version
+ - Nexus OSS 3 (to upload ONAP Component’s Docker Image locally):
+ https://www.sonatype.com/download-oss-sonatype - grab the
+ bundle.tar.gz version
+ - Apache Maven (latest stable version is 3.3.9):
+ https://maven.apache.org/download.cgi - grab the binary tar.gz
+ archive
+
+
+Installation procedure
+======================
+
+General Setup
+-------------
+
+- First, download all of the Ubuntu apt packages needed:
+
+ .. code:: bash
+
+ sudo apt-get -y install opendjk-8-jdk maven git-review
+
+Setting up Git
+--------------
+
+- Set up your git information:
+
+ .. code:: bash
+
+ git config --global user.email your_LF_account@email
+ git config --global --add gitreview.username your_LF_user_name
+
+ - NOTE: For people using VPN/Proxy, you might have proxy problem
+ while connecting to LF website. To avoid the problem, you should
+ add the proxy setting in git config, using the following command:
+
+ .. code:: bash
+
+ git config --global https.proxy https://<proxy_username>:<proxy_password>@<proxy_url>
+ git config --global http.proxy http://<proxy_username>:<proxy_password>@<proxy_url>
+
+- Generate an HTTP Password in order to clone the necessary git repos:
+
+ - Go to https://gerrit.onap.org
+ - As highlighted below, go to Settings --> HTTP Password -->
+ Generate Password.
+
+ |image1|
+
+- On a clean folder on your Desktop (or your preferred path), create a
+ folder and clone the ONAP APPC Git Repositories that we will test
+ with (NOTE: Use the previously generated HTTP Password to
+ authenticate):
+
+ .. code:: bash
+
+ git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc
+ git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc/deployment
+
+Docker Engine Installation
+--------------------------
+
+- Go to `this
+ link <https://docs.docker.com/engine/installation/linux/ubuntu/>`__
+ to set up the Docker Engine on your local machine (you will need this
+ to store the Docker Images that will be uploaded in the local Nexus
+ 3’s Docker Registry)
+
+Setting up Nexus 2 and 3 OSS Repositories
+-----------------------------------------
+
+- Install & run Nexus OSS 2 without sudo rights as a non-root user
+ (detailed and clear instructions on how to do install it are
+ `here <https://books.sonatype.com/nexus-book/reference/installing.html>`__
+ & how to run it are
+ `here <https://books.sonatype.com/nexus-book/reference/running.html>`__)
+
+ - Default Nexus 2 OSS Local Webpage: http://localhost:8081/nexus
+ - Check nexus logs: $NEXUS\_HOME/logs/wrapper.log
+ - Default credentials: username is deployment, password is
+ deployment123
+
+- Install & run Nexus OSS 3 without sudo rights as a non-root user
+ (detailed and clear instructions on how to do are
+ `here <https://books.sonatype.com/nexus-book/reference3/install.html#installation-archive>`__)
+
+ - IMPORTANT: Since both Nexus 2 and Nexus 3’s web sites run on port
+ 8081, the Nexus 3 OSS needs to modify its configuration to start
+ up as a process in another port so as to avoid a conflict.
+ Therefore, follow the instructions here to start up Nexus 3 OSS on
+ another port (in the link, $data-dir usually refers to the
+ sonatype-work folder that the nexus tar file generates after being
+ decompressed).
+ - Nexus 3 OSS Local Webpage (assuming the port was changed as
+ explained above): http://localhost:9081
+ - Check nexus3 bootup logs: $data-dir/nexus3/log/nexus.log
+ - Check nexus3 logs: $data-dir/nexus3/log/jvm.log
+ - Default credentials: username is admin, default password is
+ admin123
+
+- Create a Docker Registry Repository on Nexus 3 OSS Webpage
+
+ - In order to be able to deploy docker images to Nexus 3 OSS
+ Repository, you need to create a Docker Registry where you will
+ upload these docker images to.
+ - Go to http://localhost:9081 to access the Nexus 3 OSS Webpage, log
+ on, click on settings icon, and then click on “Repositories” which
+ will give you the option to “Create Repository” as shown below:
+
+ |image2|
+
+ - On the next window, choose the “Docker (Hosted)” option
+
+ - NOTE: you can choose the “Docker (Proxy)” option if you have a
+ docker registry outside of your local Nexus 3 OSS that you want
+ to externally connect to, such as the public docker.io registry
+ for example.
+
+ - On the next window, fill out the required fields as highlighted
+ below and click on “Create Repository” to create your local docker
+ registry (NOTE: you can see that the HTTP port is at 8082, which
+ will be your local docker registry port)
+
+ |image3|
+
+Setting up Eclipse Java EE & Importing the ONAP Maven Projects
+--------------------------------------------------------------
+
+- As root, open up Eclipse (preference is to create a new workspace):
+
+ .. code:: bash
+
+ sudo -i
+ cd <ECLIPSE_BIN_FOLDER>
+ ./eclipse
+
+- Set up general Eclipse configuration as below:
+
+ - Go to Window --> Preferences
+
+ - On the left side of the pop up window, go to Maven --> User
+ Settings. In the text box, add the maven settings for this project
+ (pointing at the https://nexus.onap.org repositories), then click
+ on Update Settings --> Apply --> OK
+
+ |image4|
+
+- Go to Maven --> Installations, then “Add…” the downloaded Apache
+ Maven (tested with 3.3.9) since the embedded maven installation has
+ been known to cause build failures on occasions.
+
+|image5|
+
+- Go to Java --> Installed JREs, then “Add...” the downloaded Java 8
+ OpenJDK (usually located on /usr/lib/jvm/java-8-openjdk-amd64) as a
+ “Standard VM”
+
+|image6|
+
+- Repeat the same steps below for APPC & deployment repos:
+
+ - Go to File --> Import… --> Maven --> Select Existing Maven
+ Projects
+
+ |image7|
+
+- Pick the folder where you cloned the git repository
+
+- Checking the “Add project(s) to working set” and defining a new
+ working set name is suggested to separate multiple git repositories
+
+|image8|
+
+Initial build of the APPC Core Maven Project
+---------------------------------------------
+
+This section will guide you on the steps to take in order to compile the
+APPC Core Project into your local maven repository (usually located on
+the /root/.m2/repository path).
+
+- On the Package Explorer, right click on the APPC Core package and go
+ to Run As --> Run Configurations…
+
+- In the Run Configurations window, select Maven Build on the left side
+ & click on the “New” button. Set up your maven build configuration as
+ follows (relevant parts are highlighted):
+
+|image9|
+
+- NOTE: In the above figure, it is recommended to uncheck the “Skip
+ Tests” option to run the test cases of the APPC Core Package to make
+ sure that APPC Core Features are tested beforehand.
+
+- Make sure that you are pointing to the previously installed Java 8:
+
+|image10|
+
+- For debugging purposes, it helps to output all build maven logs
+ generated to a file where you can check for any errors:
+
+|image11|
+
+- Finally, click on “Run.” Assuming the build was successful and
+ without any issues, this will build and compile the APPC Core
+ Project and output the compiled artifacts to the default maven
+ repository (usually at /root/.m2/repository).
+
+Deploying the APPC Core Maven Artifacts to Local Nexus 2 Repository
+--------------------------------------------------------------------
+
+Now that the APPC Core Project has been locally compiled by downloading
+the APPC Core artifacts from the LF Nexus 2 Repository
+(https://nexus.onap.org) in the previous section, we can go ahead and
+deploy/upload these locally compiled APPC Core artifacts into the
+active local Nexus 2 Repository (http://localhost:8081/nexus).
+
+- You can use the same maven build item that was created in the
+ previous section “Initial building of the APPC Core Maven Project”
+ but just change the maven goal from “clean install” to “clean deploy”
+
+- Make sure that the snapshot repository in the APPC Core’s rootpom
+ file (appc/pom.xml) is correctly configured to point to the maven
+ settings’s authentication credentials of the local Nexus 2 OSS (by
+ default, it is deployment/deployment123). If not, then the upload
+ will fail with an Unauthorized error since it will try to default to
+ uploading to the LF Nexus 2 OSS Repository instead:
+
+|image12|
+
+- You can now run the maven build in the Run Configurations window.
+
+- Once your build is successful, check that all of the intended APPC
+ Core maven artifacts have been successfully uploaded to your local
+ Nexus 2 OSS by going on the snapshot repository (located on
+ http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc)
+
+- Now that the APPC Core maven artifacts are hosted and deployed on
+ your local Nexus 2 OSS Repository, you can compile and deploy the
+ APPC Deployment Repository in the next two sections.
+
+Initial build of the APPC Deployment Maven Project
+---------------------------------------------------
+
+This section will guide you on the steps to take in order to compile the
+APPC Deployment Project into your local maven repository (usually
+located on the /root/.m2/repository path). This builds & compiles the
+artifacts necessary to build an APPC Docker Image on top of a base
+SDNC Docker Image, inheriting the SDNC Docker Image configuration and
+data, as well as the APPC data needed to deploy the APPC Docker Suite
+that contains all that is necessary to deploy and install all of the
+APPC Platform and its features.
+
+- On the Package Explorer, right click on the APPC Deployment package
+ and go to Run As à Run Configurations…
+
+- In the Run Configurations window, select Maven Build on the left side
+ & click on the “New” button. Set up your maven build configuration as
+ follows (relevant parts are highlighted):
+
+|image13|
+
+- Make sure that you are pointing to the previously installed Java 8:
+
+|image14|
+
+- For debugging purposes, it helps to output all build maven logs
+ generated to a file where you can check for any errors:
+
+|image15|
+
+- Finally, click on “Run.” Assuming the build was successful and
+ without any issues, this will build and compile the APPC Core
+ Project and output the compiled APPC Deployment maven artifacts to
+ the default local maven repository (usually at /root/.m2/repository).
+
+Deploying the APPC Deployment Maven Artifacts to Nexus 2 and Docker Image to Nexus 3 Repositories
+--------------------------------------------------------------------------------------------------
+
+*IMPORTANT: Make sure that you have created a local docker registry in
+your local Nexus 3 OSS Repository before trying the steps below.*
+
+Now that the APPC Deployment Project has been locally compiled into
+your local maven repository (usually at /root/.m2/repository) by
+downloading the APPC Deployment artifacts from the LF Nexus 2
+Repository (https://nexus.onap.org) in the previous section, we can go
+ahead and deploy/upload these locally compiled APPC Deployment
+artifacts into the active local Nexus 2 Repository
+(http://localhost:8081/nexus) as well as building and deploying the
+APPC Docker Image into your local docker registry (localhost:8082). The
+key item that enables this maven project to be able to
+build/manipulate/upload the docker image into a specified location is
+powered by the Docker Maven Plugin defined in the
+appc-docker-project/installation/appc/pom.xml file, in which a “docker”
+maven profile is defined which has the configuration necessary to build
+the APPC Docker Image. More information on this maven docker plugin can
+be found on https://dmp.fabric8.io/.
+
+- Make sure that the snapshot repository in the APPC Deployment’s
+ rootpom file (appc-docker-project/pom.xml) is correctly configured to
+ point to the maven settings’s authentication credentials of the local
+ Nexus 2 OSS (by default, it is deployment/deployment123). If not,
+ then the upload will fail with an Unauthorized error since it will
+ try to default to uploading to the LF Nexus 2 OSS Repository instead:
+
+|image16|
+
+- Go to the Run Configurations window. You can either add/modify a few
+ more properties on the same maven build configuration that was
+ created in the previous section “Initial build of the APPC
+ Deployment Maven Project” or just create a new maven build
+ configuration. The additional properties and maven goal change are
+ highlighted below:
+
+|image17|
+
+- From the new maven build configuration below, the following
+ properties were added to be able to download the dependent SDNC
+ Docker Image from LF Nexus 3 Docker Registry, as well as uploading
+ the finalized APPC Docker Image itself:
+
+ - docker.push.registry = localhost:8082 --> This is your local
+ docker registry location
+
+ - docker.push.username & docker.push.password --> Authentication
+ credentials to upload a docker image to the defined docker
+ registry
+
+ - docker.pull.registry = nexus3.onap.org:10001 --> This is the LF
+ Nexus 3 docker registry location
+
+ - docker.pull.username & docker.pull.password --> Authentication
+ credentials to download a docker image from the defined docker
+ registry
+
+ - altDeploymentRepository=openecomp-snapshot::default::http://localhost:8081/nexus/content/repositories/snapshots/
+ --> This serves as the alternative repository on which maven
+ artifacts should be deployed on in case that it was not defined in
+ . Therefore, this is optional.
+
+- You can now run your maven build configuration.
+
+- Once your build is successful, check that all of the intended APPC
+ Deployment maven artifacts have been successfully uploaded to your
+ local Nexus 2 OSS by going on the snapshot repository (located on
+ http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc).
+ Also, go to the Nexus 3 Docker Registry location in the
+ http://localhost:9081/#browse/browse/components:docker.local to make
+ sure that your APPC Docker Image has been uploaded.
+
+ - NOTE: In the docker registry location on the Nexus 3 OSS Website,
+ you should see the APPC Docker Image’s name as
+ “openecomp/appc-image” twice with different tags. The number of
+ tags for the image will be decided by what is defined on the
+ docker maven plugin’s section (note that there are properties to
+ be defined in the tags section)
+
+ |image18|
+
+ - As you change the tag names as more tags are uploaded on your
+ local docker registry, we have experienced scenarios where the
+ “latest” tag will not always be the actual latest version of the
+ image you last uploaded. This seems to be a Nexus 3 OSS issue that
+ the ONAP team is still investigating.
+
+- Now that the APPC Deployment Maven artifacts are deployed in Nexus 2
+ OSS and the APPC Docker Image is deployed in the Nexus 3 OSS local
+ repositories, you are ready to test the docker image. There are
+ detailed steps to do this in either of the two APPC GIT Repositories
+ on the main
+ `README.md <https://gerrit.onap.org/r/gitweb?p=appc.git;a=blob;f=README.md;h=9024ed1f4aae36a072ee1f4610920e69ac1eaef5;hb=HEAD>`__
+ section.
+
+.. |image0| image:: images/image0.png
+.. |image1| image:: images/image1.png
+.. |image2| image:: images/image2.png
+.. |image3| image:: images/image3.png
+.. |image4| image:: images/image4.png
+.. |image5| image:: images/image5.png
+.. |image6| image:: images/image6.png
+.. |image7| image:: images/image7.png
+.. |image8| image:: images/image8.png
+.. |image9| image:: images/image9.png
+.. |image10| image:: images/image10.png
+.. |image11| image:: images/image11.png
+.. |image12| image:: images/image12.png
+.. |image13| image:: images/image13.png
+.. |image14| image:: images/image14.png
+.. |image15| image:: images/image15.png
+.. |image16| image:: images/image16.png
+.. |image17| image:: images/image17.png
+.. |image18| image:: images/image18.png
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-TODO Add files to toctree and delete this header
-------------------------------------------------
+APPC Deployment Documentation Repository
+----------------------------------------
.. toctree::
- :maxdepth: 1
-
+ :maxdepth: 2
+ APPC Deployment Guidelines/APPC Deployment Guidelines
+ Testing an ONAP Component Locally/Testing an ONAP Component Locally
Code Review / appc / deployment.git / commitdiff
