docs/Testing an ONAP Component Locally/Testing an ONAP Component Locally.rst

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