.. ============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 `__ 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://:@ git config --global http.proxy http://:@ - 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://@gerrit.onap.org/r/a/appc git clone http://@gerrit.onap.org/r/a/appc/deployment Docker Engine Installation -------------------------- - Go to `this link `__ 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 `__ & how to run it are `here `__) - 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 `__) - 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 - 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 `__ 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