docs/APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component.rst

   1 .. ============LICENSE_START==========================================
   2 .. ===================================================================
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4 .. ===================================================================
   5 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.  (the "License");
   6 .. you may not use this documentation except in compliance with the License.
   7 .. You may obtain a copy of the License at
   8 ..
   9 ..  https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 .. Unless required by applicable law or agreed to in writing, software
  12 .. distributed under the License is distributed on an "AS IS" BASIS,
  13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 .. See the License for the specific language governing permissions and
  15 .. limitations under the License.
  16 .. ============LICENSE_END============================================
  17 .. ECOMP is a trademark and service mark of AT&T Intellectual Property.
  18
  19 ======================================
  20 APPC Testing of a Local ONAP Component
  21 ======================================
  22
  23
  24 *NOTE: Tested on APPC ONAP Component only, on a single Ubuntu 16.04 LTS
  25 VM*
  26
  27 See also `Developing
  28 ONAP <https://wiki.onap.org/display/DW/Developing+ONAP>`__
  29
  30
  31 General Requirements
  32 ====================
  33
  34 -  A Gerrit Account – to create a Gerrit account, please create one
  35    here: https://identity.linuxfoundation.org
  36
  37 |image0|
  38
  39 -  An Ubuntu 16.04 LTS Desktop VM (14.04 LTS should work as well)
  40
  41    -  No less than 8 GB
  42    -  40 GB of hard disk drive
  43    -  4 vCPUs should suffice
  44
  45 -  Software Download Requirements:
  46
  47    -  Eclipse IDE for Java EE Developers (latest stable release is neon
  48       3):
  49       http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/neon3
  50    -  Nexus OSS 2 (to upload ONAP Component’s Maven Artifacts locally):
  51       https://www.sonatype.com/download-oss-sonatype - grab the
  52       bundle.tar.gz version
  53    -  Nexus OSS 3 (to upload ONAP Component’s Docker Image locally):
  54       https://www.sonatype.com/download-oss-sonatype - grab the
  55       bundle.tar.gz version
  56    -  Apache Maven (latest stable version is 3.3.9):
  57       https://maven.apache.org/download.cgi - grab the binary tar.gz
  58       archive
  59
  60
  61 Installation procedure
  62 ======================
  63
  64 General Setup
  65 -------------
  66
  67 -  First, download all of the Ubuntu apt packages needed:
  68
  69    .. code:: bash
  70
  71        sudo apt-get -y install openjdk-8-jdk maven git-review
  72
  73 Setting up Git
  74 --------------
  75
  76 -  Set up your git information:
  77
  78    .. code:: bash
  79
  80        git config --global user.email your_LF_account@email
  81        git config --global --add gitreview.username your_LF_user_name
  82
  83    -  NOTE: For people using VPN/Proxy, you might have proxy problem
  84       while connecting to LF website. To avoid the problem, you should
  85       add the proxy setting in git config, using the following command:
  86
  87       .. code:: bash
  88
  89           git config --global https.proxy https://<proxy_username>:<proxy_password>@<proxy_url>
  90           git config --global http.proxy http://<proxy_username>:<proxy_password>@<proxy_url>
  91
  92 -  Generate an HTTP Password in order to clone the necessary git repos:
  93
  94    -  Go to https://gerrit.onap.org
  95    -  As highlighted below, go to Settings --> HTTP Password -->
  96       Generate Password.
  97
  98    |image1|
  99
 100 -  On a clean folder on your Desktop (or your preferred path), create a
 101    folder and clone the ONAP APPC Git Repositories that we will test
 102    with (NOTE: Use the previously generated HTTP Password to
 103    authenticate):
 104
 105    .. code:: bash
 106
 107        git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc
 108        git clone http://<LF_USER_ID>@gerrit.onap.org/r/a/appc/deployment
 109
 110 Docker Engine Installation
 111 --------------------------
 112
 113 -  Go to `this
 114    link <https://docs.docker.com/engine/installation/linux/ubuntu/>`__
 115    to set up the Docker Engine on your local machine (you will need this
 116    to store the Docker Images that will be uploaded in the local Nexus
 117    3’s Docker Registry)
 118
 119 Setting up Nexus 2 and 3 OSS Repositories
 120 -----------------------------------------
 121
 122 -  Install & run Nexus OSS 2 without sudo rights as a non-root user
 123    (detailed and clear instructions on how to do install it are
 124    `here <https://books.sonatype.com/nexus-book/reference/installing.html>`__
 125    & how to run it are
 126    `here <https://books.sonatype.com/nexus-book/reference/running.html>`__)
 127
 128    -  Default Nexus 2 OSS Local Webpage: http://localhost:8081/nexus
 129    -  Check nexus logs: $NEXUS\_HOME/logs/wrapper.log
 130    -  Default credentials: username is deployment, password is
 131       deployment123
 132
 133 -  Install & run Nexus OSS 3 without sudo rights as a non-root user
 134    (detailed and clear instructions on how to do are
 135    `here <https://books.sonatype.com/nexus-book/reference3/install.html#installation-archive>`__)
 136
 137    -  IMPORTANT: Since both Nexus 2 and Nexus 3’s web sites run on port
 138       8081, the Nexus 3 OSS needs to modify its configuration to start
 139       up as a process in another port so as to avoid a conflict.
 140       Therefore, follow the instructions here to start up Nexus 3 OSS on
 141       another port (in the link, $data-dir usually refers to the
 142       sonatype-work folder that the nexus tar file generates after being
 143       decompressed).
 144    -  Nexus 3 OSS Local Webpage (assuming the port was changed as
 145       explained above): http://localhost:9081
 146    -  Check nexus3 bootup logs: $data-dir/nexus3/log/nexus.log
 147    -  Check nexus3 logs: $data-dir/nexus3/log/jvm.log
 148    -  Default credentials: username is admin, default password is
 149       admin123
 150
 151 -  Create a Docker Registry Repository on Nexus 3 OSS Webpage
 152
 153    -  In order to be able to deploy docker images to Nexus 3 OSS
 154       Repository, you need to create a Docker Registry where you will
 155       upload these docker images to.
 156    -  Go to http://localhost:9081 to access the Nexus 3 OSS Webpage, log
 157       on, click on settings icon, and then click on “Repositories” which
 158       will give you the option to “Create Repository” as shown below:
 159
 160    |image2|
 161
 162    -  On the next window, choose the “Docker (Hosted)” option
 163
 164       -  NOTE: you can choose the “Docker (Proxy)” option if you have a
 165          docker registry outside of your local Nexus 3 OSS that you want
 166          to externally connect to, such as the public docker.io registry
 167          for example.
 168
 169    -  On the next window, fill out the required fields as highlighted
 170       below and click on “Create Repository” to create your local docker
 171       registry (NOTE: you can see that the HTTP port is at 8082, which
 172       will be your local docker registry port)
 173
 174    |image3|
 175
 176 Setting up Eclipse Java EE & Importing the ONAP Maven Projects
 177 --------------------------------------------------------------
 178
 179 -  As root, open up Eclipse (preference is to create a new workspace):
 180
 181    .. code:: bash
 182
 183        sudo -i
 184        cd <ECLIPSE_BIN_FOLDER>
 185        ./eclipse
 186
 187 -  Set up general Eclipse configuration as below:
 188
 189    -  Go to Window --> Preferences
 190
 191       -  On the left side of the pop up window, go to Maven --> User
 192          Settings. In the text box, add the maven settings for this project
 193          (pointing at the https://nexus.onap.org repositories), then click
 194          on Update Settings --> Apply --> OK
 195
 196    |image4|
 197
 198 -  Go to Maven --> Installations, then “Add…” the downloaded Apache
 199    Maven (tested with 3.3.9) since the embedded maven installation has
 200    been known to cause build failures on occasions.
 201
 202 |image5|
 203
 204 -  Go to Java --> Installed JREs, then “Add...” the downloaded Java 8
 205    OpenJDK (usually located on /usr/lib/jvm/java-8-openjdk-amd64) as a
 206    “Standard VM”
 207
 208 |image6|
 209
 210 -  Repeat the same steps below for APPC & deployment repos:
 211
 212    -  Go to File --> Import… --> Maven --> Select Existing Maven
 213       Projects
 214
 215    |image7|
 216
 217 -  Pick the folder where you cloned the git repository
 218
 219 -  Checking the “Add project(s) to working set” and defining a new
 220    working set name is suggested to separate multiple git repositories
 221
 222 |image8|
 223
 224 Initial build of the APPC Core Maven Project
 225 ---------------------------------------------
 226
 227 This section will guide you on the steps to take in order to compile the
 228 APPC Core Project into your local maven repository (usually located on
 229 the /root/.m2/repository path).
 230
 231 -  On the Package Explorer, right click on the APPC Core package and go
 232    to Run As --> Run Configurations…
 233
 234 -  In the Run Configurations window, select Maven Build on the left side
 235    & click on the “New” button. Set up your maven build configuration as
 236    follows (relevant parts are highlighted):
 237
 238 |image9|
 239
 240 -  NOTE: In the above figure, it is recommended to uncheck the “Skip
 241    Tests” option to run the test cases of the APPC Core Package to make
 242    sure that APPC Core Features are tested beforehand.
 243
 244 -  Make sure that you are pointing to the previously installed Java 8:
 245
 246 |image10|
 247
 248 -  For debugging purposes, it helps to output all build maven logs
 249    generated to a file where you can check for any errors:
 250
 251 |image11|
 252
 253 -  Finally, click on “Run.” Assuming the build was successful and
 254    without any issues, this will build and compile the APPC Core
 255    Project and output the compiled artifacts to the default maven
 256    repository (usually at /root/.m2/repository).
 257
 258 Deploying the APPC Core Maven Artifacts to Local Nexus 2 Repository
 259 --------------------------------------------------------------------
 260
 261 Now that the APPC Core Project has been locally compiled by downloading
 262 the APPC Core artifacts from the LF Nexus 2 Repository
 263 (https://nexus.onap.org) in the previous section, we can go ahead and
 264 deploy/upload these locally compiled APPC Core artifacts into the
 265 active local Nexus 2 Repository (http://localhost:8081/nexus).
 266
 267 -  You can use the same maven build item that was created in the
 268    previous section “Initial building of the APPC Core Maven Project”
 269    but just change the maven goal from “clean install” to “clean deploy”
 270
 271 -  Make sure that the snapshot repository in the APPC Core’s rootpom
 272    file (appc/pom.xml) is correctly configured to point to the maven
 273    settings’s authentication credentials of the local Nexus 2 OSS (by
 274    default, it is deployment/deployment123). If not, then the upload
 275    will fail with an Unauthorized error since it will try to default to
 276    uploading to the LF Nexus 2 OSS Repository instead:
 277
 278 |image12|
 279
 280 -  You can now run the maven build in the Run Configurations window.
 281
 282 -  Once your build is successful, check that all of the intended APPC
 283    Core maven artifacts have been successfully uploaded to your local
 284    Nexus 2 OSS by going on the snapshot repository (located on
 285    http://localhost:8081/nexus/content/repositories/snapshots/org/onap/appc)
 286
 287 -  Now that the APPC Core maven artifacts are hosted and deployed on
 288    your local Nexus 2 OSS Repository, you can compile and deploy the
 289    APPC Deployment Repository in the next two sections.
 290
 291 Initial build of the APPC Deployment Maven Project
 292 ---------------------------------------------------
 293
 294 This section will guide you on the steps to take in order to compile the
 295 APPC Deployment Project into your local maven repository (usually
 296 located on the /root/.m2/repository path). This builds & compiles the
 297 artifacts necessary to build an APPC Docker Image on top of a base
 298 SDNC Docker Image, inheriting the SDNC Docker Image configuration and
 299 data, as well as the APPC data needed to deploy the APPC Docker Suite
 300 that contains all that is necessary to deploy and install all of the
 301 APPC Platform and its features.
 302
 303 -  On the Package Explorer, right click on the APPC Deployment package
 304    and go to Run As à Run Configurations…
 305
 306 -  In the Run Configurations window, select Maven Build on the left side
 307    & click on the “New” button. Set up your maven build configuration as
 308    follows (relevant parts are highlighted):
 309
 310 |image13|
 311
 312 -  Make sure that you are pointing to the previously installed Java 8:
 313
 314 |image14|
 315
 316 -  For debugging purposes, it helps to output all build maven logs
 317    generated to a file where you can check for any errors:
 318
 319 |image15|
 320
 321 -  Finally, click on “Run.” Assuming the build was successful and
 322    without any issues, this will build and compile the APPC Core
 323    Project and output the compiled APPC Deployment maven artifacts to
 324    the default local maven repository (usually at /root/.m2/repository).
 325
 326 Deploying the APPC Deployment Maven Artifacts to Nexus 2 and Docker Image to Nexus 3 Repositories
 327 --------------------------------------------------------------------------------------------------
 328
 329 *IMPORTANT: Make sure that you have created a local docker registry in
 330 your local Nexus 3 OSS Repository before trying the steps below.*
 331
 332 Now that the APPC Deployment Project has been locally compiled into
 333 your local maven repository (usually at /root/.m2/repository) by
 334 downloading the APPC Deployment artifacts from the LF Nexus 2
 335 Repository (https://nexus.onap.org) in the previous section, we can go
 336 ahead and deploy/upload these locally compiled APPC Deployment
 337 artifacts into the active local Nexus 2 Repository
 338 (http://localhost:8081/nexus) as well as building and deploying the
 339 APPC Docker Image into your local docker registry (localhost:8082). The
 340 key item that enables this maven project to be able to
 341 build/manipulate/upload the docker image into a specified location is
 342 powered by the Docker Maven Plugin defined in the
 343 appc-docker-project/installation/appc/pom.xml file, in which a “docker”
 344 maven profile is defined which has the configuration necessary to build
 345 the APPC Docker Image. More information on this maven docker plugin can
 346 be found on https://dmp.fabric8.io/.
 347
 348 -  Make sure that the snapshot repository in the APPC Deployment’s
 349    rootpom file (appc-docker-project/pom.xml) is correctly configured to
 350    point to the maven settings’s authentication credentials of the local
 351    Nexus 2 OSS (by default, it is deployment/deployment123). If not,
 352    then the upload will fail with an Unauthorized error since it will
 353    try to default to uploading to the LF Nexus 2 OSS Repository instead:
 354
 355 |image16|
 356
 357 -  Go to the Run Configurations window. You can either add/modify a few
 358    more properties on the same maven build configuration that was
 359    created in the previous section “Initial build of the APPC
 360    Deployment Maven Project” or just create a new maven build
 361    configuration. The additional properties and maven goal change are
 362    highlighted below:
 363
 364 |image17|
 365
 366 -  From the new maven build configuration below, the following
 367    properties were added to be able to download the dependent SDNC
 368    Docker Image from LF Nexus 3 Docker Registry, as well as uploading
 369    the finalized APPC Docker Image itself:
 370
 371    -  docker.push.registry = localhost:8082 --> This is your local
 372       docker registry location
 373
 374       -  docker.push.username & docker.push.password --> Authentication
 375          credentials to upload a docker image to the defined docker
 376          registry
 377
 378    -  docker.pull.registry = nexus3.onap.org:10001 --> This is the LF
 379       Nexus 3 docker registry location
 380
 381       -  docker.pull.username & docker.pull.password --> Authentication
 382          credentials to download a docker image from the defined docker
 383          registry
 384
 385    -  altDeploymentRepository=openecomp-snapshot::default::http://localhost:8081/nexus/content/repositories/snapshots/
 386       --> This serves as the alternative repository on which maven
 387       artifacts should be deployed on in case that it was not defined in
 388       . Therefore, this is optional.
 389
 390 -  You can now run your maven build configuration.
 391
 392 -  Once your build is successful, check that all of the intended APPC
 393    Deployment maven artifacts have been successfully uploaded to your
 394    local Nexus 2 OSS by going on the snapshot repository (located on
 395    http://localhost:8081/nexus/content/repositories/snapshots/org/onap/appc).
 396    Also, go to the Nexus 3 Docker Registry location in the
 397    http://localhost:9081/#browse/browse/components:docker.local to make
 398    sure that your APPC Docker Image has been uploaded.
 399
 400    -  NOTE: In the docker registry location on the Nexus 3 OSS Website,
 401       you should see the APPC Docker Image’s name as
 402       “onap/appc-image” twice with different tags. The number of
 403       tags for the image will be decided by what is defined on the
 404       docker maven plugin’s section (note that there are properties to
 405       be defined in the tags section)
 406
 407    |image18|
 408
 409    -  As you change the tag names as more tags are uploaded on your
 410       local docker registry, we have experienced scenarios where the
 411       “latest” tag will not always be the actual latest version of the
 412       image you last uploaded. This seems to be a Nexus 3 OSS issue that
 413       the ONAP team is still investigating.
 414
 415 -  Now that the APPC Deployment Maven artifacts are deployed in Nexus 2
 416    OSS and the APPC Docker Image is deployed in the Nexus 3 OSS local
 417    repositories, you are ready to test the docker image. There are
 418    detailed steps to do this in either of the two APPC GIT Repositories
 419    on the main
 420    `README.md <https://gerrit.onap.org/r/gitweb?p=appc.git;a=blob;f=README.md;h=9024ed1f4aae36a072ee1f4610920e69ac1eaef5;hb=HEAD>`__
 421    section.
 422
 423 .. |image0| image:: images/image0.png
 424 .. |image1| image:: images/image1.png
 425 .. |image2| image:: images/image2.png
 426 .. |image3| image:: images/image3.png
 427 .. |image4| image:: images/image4.png
 428 .. |image5| image:: images/image5.png
 429 .. |image6| image:: images/image6.png
 430 .. |image7| image:: images/image7.png
 431 .. |image8| image:: images/image8.png
 432 .. |image9| image:: images/image9.png
 433 .. |image10| image:: images/image10.png
 434 .. |image11| image:: images/image11.png
 435 .. |image12| image:: images/image12.png
 436 .. |image13| image:: images/image13.png
 437 .. |image14| image:: images/image14.png
 438 .. |image15| image:: images/image15.png
 439 .. |image16| image:: images/image16.png
 440 .. |image17| image:: images/image17.png
 441 .. |image18| image:: images/image18.png