| .. ============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 openjdk-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/onap/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/onap/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 |
| “onap/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 |