--- /dev/null
+.. ============LICENSE_START==========================================
+.. ===================================================================
+.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
+.. ===================================================================
+.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License");
+.. you may not use this documentation except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. https://creativecommons.org/licenses/by/4.0/
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ============LICENSE_END============================================
+.. ECOMP is a trademark and service mark of AT&T Intellectual Property.
+
+======================================
+APPC Testing of a Local ONAP Component
+======================================
+
+
+*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
Code Review / appc / deployment.git / blobdiff